Next.js: 环境搭建与项目结构

# 一条交互式命令，回答几个简单问题即可
npx create-next-app@latest taskflow --ts --tailwind --app --src-dir --import-alias "@/*"

# 运行脚手架命令
npx create-next-app@latest

? What is your project named?  taskflow
? Would you like to use TypeScript?  Yes / No
? Would you like to use ESLint?  Yes / No
? Would you like to use Tailwind CSS?  Yes / No
? Would you like to use `src/` directory?  Yes / No
? Would you like to use App Router? (recommended)  Yes / No
? Would you like to customize the import alias (`@/*` by default)?  No

# 本课程的推荐选项（所有项目都使用这一组）
npx create-next-app@latest taskflow ^
  --typescript ^
  --eslint ^
  --tailwind ^
  --src-dir ^
  --app ^
  --import-alias "@/*"

# ============================================
# 创建名为 shophub 的新项目
# ============================================

npx create-next-app@latest shophub --ts --tailwind --app --src-dir

# 控制台输出
cd shophub
npm run dev

Creating a new Next.js project in C:\Users\Charlie\shophub.

✔ Would you like to use TypeScript? … Yes
✔ Would you like to use ESLint? … Yes
✔ Would you like to use Tailwind CSS? … Yes
✔ Would you like to use `src/` directory? … Yes
✔ Would you like to use App Router? (recommended) … Yes
✔ Would you like to customize the import alias? … @/*

Success! Created shophub at shophub
Inside that directory, you can run:
  npm run dev       # 启动开发服务器
  npm run build     # 构建生产版本
  npm start         # 启动生产服务器

// ============================================
// create-next-app 默认生成的首页
// ============================================

import Image from "next/image";

export default function Home() {
  return (
    <div className="grid grid-rows-[20px_1fr_20px] items-center justify-items-center min-h-screen p-8 pb-20 gap-16 sm:p-20 font-[family-name:var(--font-geist-sans)]">
      <main className="flex flex-col gap-8 row-start-2 items-center sm:items-start">
        <Image
          className="dark:invert"
          src="/next.svg"
          alt="Next.js logo"
          width={180}
          height={38}
          priority
        />
        <ol className="list-inside list-decimal text-sm text-center sm:text-left font-[family-name:var(--font-geist-mono)]">
          <li className="mb-2">
            Get started by editing{" "}
            <code className="bg-black/[.05] dark:bg-white/[.06] px-1 py-0.5 rounded font-semibold">
              src/app/page.tsx
            </code>
          </li>
          <li>Save and see your changes instantly.</li>
        </ol>
        <div className="flex gap-4 items-center flex-col sm:flex-row">
          <a className="...">Deploy now</a>
          <a className="...">Read our docs</a>
        </div>
      </main>
    </div>
  );
}

在浏览器中打开 http://localhost:3000，可以看到：
- Next.js 官方 Logo
- "Get started by editing src/app/page.tsx" 提示
- "Deploy now" 和 "Read our docs" 两个链接
- 深色/浅色主题自适应

public/
├── favicon.ico      # 浏览器标签页图标
├── file.svg         # 文件类型图标
├── globe.svg        # 地球图标
├── next.svg         # Next.js Logo
├── vercel.svg       # Vercel Logo
└── window.svg       # 窗口图标

// 在组件中引用 public 目录下的图片
<img src="/logo.png" alt="Logo" />
// 或使用 next/image 组件
import Image from 'next/image';
<Image src="/logo.png" alt="Logo" width={200} height={100} />

// ============================================
// next.config.ts — Next.js 编译时配置
// ============================================

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // 允许从指定域名加载外部图片
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "fakestoreapi.com",
      },
      {
        protocol: "https",
        hostname: "images.unsplash.com",
      },
    ],
  },

  // 启用 PPR（Partial Prerendering）
  experimental: {
    ppr: true,
  },
};

export default nextConfig;

配置生效后：
1. <Image> 组件可以加载 fakestoreapi.com 和 images.unsplash.com 的图片
2. 页面中 Suspense 边界后面的内容会使用 PPR 流式渲染
3. 重新运行 npm run dev 后配置生效

# 进入项目目录
cd shophub

# 启动开发服务器
npm run dev

# ============================================
# 启动开发服务器，观察 Turbopack 的极速 HMR
# ============================================

npm run dev

# 控制台输出
> shophub@0.1.0 dev
> next dev

  ▲  ▲
  ▲  Next.js 16.2
  ▲  - Local: http://localhost:3000
  ▲  - Turbopack: ✓ loaded in 742ms

✔ Compiled /src/app/page.tsx in 142ms (modules: 523)

✔ Updated /src/app/page.tsx in 4ms    ← 4 毫秒！几乎瞬间更新

# 构建生产版本
npm run build

✓ Linting and checking validity of types
✓ Collecting page data
✓ Generating static pages (5/5)
✓ Collecting build traces
✓ Finalizing page optimization

Route (app)                              Size     First Load JS
┌ ○ /                                    5.1 kB          89 kB
├ ○ /_not-found                          152 B          84.1 kB
└ λ /api/hello                           0 B            84.1 kB
+ First Load JS shared by all            84.1 kB
  ├ chunks/main-app                      ...
  └ chunks/webpack                       ...

○  (Static)  静态生成（SSG）
λ  (Dynamic) 动态渲染（SSR）

# ============================================
# 生产构建输出解读
# ============================================

# 假设创建了两个页面：
# app/about/page.tsx 和 app/dashboard/page.tsx
# 其中 dashboard 使用了 cookies() 动态函数

npm run build

# 输出中的符号含义：
○  /              # 静态页面（无动态函数）
○  /about         # 静态页面
λ  /dashboard     # 动态页面（使用了动态 API）
○  /_not-found    # 404 页面

Route (app)                              Size     First Load JS
┌ ○ /                                    5.1 kB          89 kB
├ ○ /about                               3.2 kB          87 kB
├ λ /dashboard                           6.8 kB          92 kB
└ ○ /_not-found                          152 B          84.1 kB

# 构建后启动生产服务器
npm run build
npm start

{
  "name": "shophub",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "next": "^16.2.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0",
    "typescript": "^5.7.0",
    "tailwindcss": "^4.0.0",
    "eslint": "^9.0.0",
    "@eslint/eslintrc": "^3.0.0"
  }
}

// ============================================
// 在 package.json 中添加常用的自定义脚本
// ============================================

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "type-check": "tsc --noEmit",
    "format": "prettier --write .",
    "preview": "npm run build && npm start"
  }
}

npm run type-check   → 运行 TypeScript 类型检查（不输出文件）
npm run format       → 用 Prettier 格式化全部代码
npm run preview      → 先构建再启动生产服务器（一条命令完成）

// ============================================
// .vscode/settings.json — 项目级 VS Code 配置
// ============================================

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ],
  "typescript.preferences.importModuleSpecifier": "non-relative"
}

配置生效后：
1. 每次保存文件自动格式化（Prettier）
2. 自动修复 ESLint 问题
3. Tailwind CSS 类名自动补全（输入 "flex" → 提示所有 flex 变体）
4. TypeScript 导入使用 @/ 别名路径

// ============================================
// 使用 ES7+ React 插件创建新页面
// 新建文件 src/app/about/page.tsx
// 输入 "rafce" 回车，自动生成模板
// ============================================

// 输入 rafce → 自动展开为：
import React from 'react'

const page = () => {
  return (
    <div>page</div>
  )
}

export default page

// 手动修改为实际页面内容：
export default function AboutPage() {
  return (
    <div className="p-8">
      <h1 className="text-3xl font-bold">About Us</h1>
      <p className="mt-4 text-gray-600">
        TaskFlow helps teams collaborate on projects.
      </p>
    </div>
  );
}

在浏览器访问 http://localhost:3000/about
看到：
About Us
TaskFlow helps teams collaborate on projects.

# ============================================
# 综合示例：从零搭建完整的 Next.js 16 项目
# TaskFlow — 项目协同管理平台
# ============================================

# 1. 创建项目
npx create-next-app@latest taskflow ^
  --typescript ^
  --eslint ^
  --tailwind ^
  --src-dir ^
  --app ^
  --import-alias "@/*"

# 2. 进入项目目录
cd taskflow

# 3. 查看目录结构
tree . /F | findstr /r "^.*src" > nul && dir /s /b src

# 4. 启动开发服务器
npm run dev

# 5. 在另一个终端中，添加推荐的 VS Code 配置
mkdir .vscode

// .vscode/settings.json — 项目级配置
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.preferences.importModuleSpecifier": "non-relative"
}

// src/app/page.tsx — 修改首页为 TaskFlow 欢迎页
import Link from "next/link";

export default function Home() {
  return (
    <div className="min-h-screen bg-gradient-to-br from-blue-50 to-indigo-100">
      <div className="container mx-auto px-4 py-16 text-center">
        <h1 className="text-5xl font-bold text-gray-900 mb-4">
          TaskFlow
        </h1>
        <p className="text-xl text-gray-600 mb-8 max-w-2xl mx-auto">
          A collaborative project management platform built with Next.js 16.
          Plan, track, and deliver projects together.
        </p>
        <div className="flex gap-4 justify-center">
          <Link
            href="/login"
            className="px-6 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
          >
            Get Started
          </Link>
          <Link
            href="/about"
            className="px-6 py-3 border border-gray-300 rounded-lg hover:bg-gray-50"
          >
            Learn More
          </Link>
        </div>
        <div className="mt-16 grid grid-cols-3 gap-8 max-w-3xl mx-auto">
          <div className="p-6 bg-white rounded-xl shadow-sm">
            <h3 className="font-bold text-lg">Plan</h3>
            <p className="text-gray-500 mt-2">Create projects and assign tasks</p>
          </div>
          <div className="p-6 bg-white rounded-xl shadow-sm">
            <h3 className="font-bold text-lg">Track</h3>
            <p className="text-gray-500 mt-2">Monitor progress in real-time</p>
          </div>
          <div className="p-6 bg-white rounded-xl shadow-sm">
            <h3 className="font-bold text-lg">Deliver</h3>
            <p className="text-gray-500 mt-2">Ship projects on schedule</p>
          </div>
        </div>
      </div>
    </div>
  );
}

在浏览器 http://localhost:3000 看到：

[TaskFlow 标题]
A collaborative project management platform built with Next.js 16.
Plan, track, and deliver projects together.

[Get Started] [Learn More]

┌──────┐  ┌──────┐  ┌──────┐
│ Plan │  │ Track│  │Deliver│
└──────┘  └──────┘  └──────┘