2. 项目结构与配置

顶层目录

用 create-next-app 创建的项目，根目录长这样：

my-app/
├── app/              # App Router 的页面和组件
├── public/           # 静态资源（图片、字体等）
├── .next/            # 构建产物（自动生成）
├── node_modules/     # 依赖包
├── next.config.ts    # Next.js 配置
├── tsconfig.json     # TypeScript 配置
├── package.json      # 项目依赖和脚本
└── eslint.config.mjs # ESLint 配置

顶层文件夹

文件夹	用途
app/	App Router，放页面和布局
pages/	Pages Router（旧版路由），和 app/ 二选一
public/	静态文件，通过 / 路径直接访问
src/	可选，把代码放这里区分源码和配置

顶层文件

文件	用途
next.config.ts	Next.js 核心配置
package.json	依赖、脚本、项目元信息
tsconfig.json	TypeScript 编译选项
.env	环境变量
eslint.config.mjs	代码检查配置
next-env.d.ts	Next.js 类型声明（自动生成）

路由文件约定

App Router 有一套特殊的文件名，每个名字对应不同的功能：

文件名	作用
page.tsx	页面，定义公开路由
layout.tsx	布局，包裹子页面
loading.tsx	加载态，自动包裹 Suspense
error.tsx	错误边界，捕获渲染错误
not-found.tsx	404 页面
global-error.tsx	全局错误边界
route.ts	API 路由（后端接口）
template.tsx	类似 layout，但每次导航重新渲染
default.tsx	并行路由的兜底页面

这些文件名是约定好的，不能改名。Next.js 靠它们识别路由结构。

嵌套路由

文件夹的层级对应 URL 的层级：

文件路径	对应 URL
app/page.tsx	/
app/blog/page.tsx	/blog
app/blog/authors/page.tsx	/blog/authors

只有包含 page.tsx 或 route.ts 的路径才是公开路由。其他文件不会暴露为 URL。

动态路由

用方括号命名文件夹，可以创建动态路由：

文件路径	匹配的 URL
app/blog/[slug]/page.tsx	/blog/my-first-post
app/shop/[...slug]/page.tsx	/shop/clothes/shirts
app/docs/[[...slug]]/page.tsx	/docs 或 /docs/a/b

• [slug]：单段参数
• [...slug]：捕获所有后续段（catch-all）
• [[...slug]]：可选 catch-all，也匹配不带参数的情况

路由组

用括号包裹文件夹名，可以创建路由组——不影响 URL，只用于组织代码：

app/
├── (marketing)/
│   ├── layout.tsx
│   └── page.tsx      # URL: /
├── (shop)/
│   ├── cart/
│   │   └── page.tsx  # URL: /cart
│   └── account/
│       └── page.tsx  # URL: /account

(marketing) 和 (shop) 不会出现在 URL 里。路由组常用于给不同模块设置不同布局。

私有文件夹

用下划线开头的文件夹是私有的，不参与路由：

app/blog/
├── _components/
│   └── Post.tsx      # 不是路由，只是组件
├── _lib/
│   └── data.ts       # 不是路由，只是工具函数
└── page.tsx          # /blog

私有文件夹用来把组件、工具函数就近放在使用它们的路由旁边，又不用担心被误识别为路由。

next.config.ts 配置

next.config.ts 是 Next.js 的核心配置文件。新建项目默认是空的：

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  // 配置项写在这里
}

export default nextConfig

常用配置项：

const nextConfig: NextConfig = {
  // 启用 Cache Components（Next.js 16 新特性）
  cacheComponents: true,

  // 图片优化配置
  images: {
    remotePatterns: [
      { hostname: 'example.com' },
    ],
  },

  // 自定义 Webpack（如果需要）
  webpack: (config) => {
    return config
  },

  // 环境变量暴露给客户端
  env: {
    CUSTOM_KEY: 'value',
  },
}

tsconfig.json 配置

TypeScript 配置文件，Next.js 会自动生成推荐配置：

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      { "name": "next" }
    ],
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types.ts"],
  "exclude": ["node_modules"]
}

重点看 paths 配置——@/* 映射到项目根目录，这样你可以用 @/components/Button 代替 ../../../components/Button。

package.json 配置

{
  "name": "my-app",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
  },
  "dependencies": {
    "next": "16.2.12",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "typescript": "^5",
    "@types/node": "^20",
    "@types/react": "^19",
    "tailwindcss": "^4",
    "eslint": "^9",
    "eslint-config-next": "16.2.12"
  }
}

scripts 里的命令对应开发流程：

1. npm run dev：本地开发
2. npm run build：构建生产版本
3. npm start：启动生产服务器
4. npm run lint：代码检查

路径别名

Next.js 支持配置路径别名，让导入更干净：

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": "src/",
    "paths": {
      "@/styles/*": ["styles/*"],
      "@/components/*": ["components/*"]
    }
  }
}

配置后：

// 之前
import { Button } from '../../../components/button'

// 之后
import { Button } from '@/components/button'

组件层级关系

特殊文件之间有固定的嵌套顺序：

layout.tsx        # 最外层
  └── template.tsx
      └── error.tsx
          └── loading.tsx
              └── not-found.tsx
                  └── page.tsx  # 最内层

理解这个层级很重要——它决定了错误边界、加载态的作用范围。

小结

这一章我们拆解了项目的目录结构：

1. 顶层有 app/、public/、配置文件
2. 特殊文件名（page、layout、loading 等）有固定含义
3. 文件夹层级对应 URL，动态路由用方括号
4. next.config.ts、tsconfig.json、package.json 各司其职

下一章，我们来学习 App Router 的核心概念——layout 和 page。