编辑“︁Next.js文件结构”︁（章节）

= Next.js文件结构 =

== 介绍 ==

Next.js的文件结构是项目组织的基础，它定义了路由、页面、API端点、静态资源和配置的存放位置。理解这种结构对于高效开发至关重要，因为它直接影响路由系统、代码分割和构建优化。Next.js采用约定优于配置（Convention over Configuration）的原则，通过特定的目录和文件名自动处理路由等逻辑。

== 核心目录与文件 ==

以下是典型的Next.js项目结构（基于最新版本）：

<syntaxhighlight lang="bash">
my-next-app/
├── .next/                  # 构建输出目录（自动生成）
├── public/                 # 静态资源
│   ├── favicon.ico
│   └── images/
├── src/                    # 可选：推荐存放应用代码
│   ├── app/                # App Router（Next.js 13+）
│   │   ├── page.js         # 首页路由
│   │   └── about/page.js   # 嵌套路由
│   ├── pages/              # Pages Router（传统方式）
│   │   ├── _app.js         # 自定义App组件
│   │   ├── _document.js    # HTML文档结构
│   │   └── api/            # API路由
│   ├── components/         # 可复用UI组件
│   ├── styles/             # CSS/SCSS文件
│   └── lib/                # 工具函数库
├── next.config.js          # Next.js配置
└── package.json
</syntaxhighlight>

=== 新旧路由系统对比 ===
Next.js 13+引入了基于<code>app/</code>目录的App Router，与传统的<code>pages/</code>目录并行支持：

{| class="wikitable"
! 特性 !! App Router !! Pages Router
|-
| 路由定义 || 文件夹结构 || 文件路径
|-
| 布局 || <code>layout.js</code> || <code>_app.js</code>
|-
| 嵌套路由 || 原生支持 || 需手动配置
|-
| 数据获取 || 服务端组件优先 || 客户端为主
|}

== 关键文件详解 ==

=== 页面文件 ===
在<code>pages/</code>目录下，每个<code>.js</code>/<code>.tsx</code>文件自动成为路由：

<syntaxhighlight lang="javascript">
// pages/about.js
export default function About() {
  return <div>关于我们</div>;
}
</syntaxhighlight>

访问路径：<code>/about</code>

=== 动态路由 ===
使用方括号命名文件实现动态路由：

<syntaxhighlight lang="javascript">
// pages/posts/[id].js
import { useRouter } from 'next/router';

export default function Post() {
  const router = useRouter();
  const { id } = router.query;

  return <div>文章ID: {id}</div>;
}
</syntaxhighlight>

访问<code>/posts/123</code>将显示"文章ID: 123"

=== API路由 ===
<code>pages/api/</code>下的文件创建API端点：

<syntaxhighlight lang="javascript">
// pages/api/hello.js
export default function handler(req, res) {
  res.status(200).json({ name: 'Next.js' });
}
</syntaxhighlight>

通过<code>/api/hello</code>访问此端点

== 特殊文件 ==

=== _app.js ===
自定义应用外壳，常用于：
* 全局样式
* 状态管理初始化
* 布局组件

<syntaxhighlight lang="javascript">
// pages/_app.js
import '../styles/globals.css';

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

export default MyApp;
</syntaxhighlight>

=== _document.js ===
自定义HTML文档结构：

<syntaxhighlight lang="javascript">
// pages/_document.js
import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html lang="zh-CN">
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}
</syntaxhighlight>

== 静态资源 ==

<code>public/</code>目录下的文件可通过根路径直接访问：

```bash
public/images/logo.png → /images/logo.png
```

== 配置文件 ==

<code>next.config.js</code>允许自定义构建行为：

<syntaxhighlight lang="javascript">
// next.config.js
module.exports = {
  images: {
    domains: ['example.com'],
  },
  async redirects() {
    return [
      {
        source: '/old',
        destination: '/new',
        permanent: true,
      },
    ];
  },
};
</syntaxhighlight>

== 可视化结构 ==

<mermaid>
graph TD
    A[Next.js项目] --> B[public/]
    A --> C[src/]
    C --> D[app/ 或 pages/]
    C --> E[components/]
    C --> F[styles/]
    A --> G[next.config.js]
    D --> H[page.js]
    D --> I[layout.js]
    D --> J[api/]
</mermaid>

== 最佳实践 ==

1. '''路由组织''':
   * 使用<code>pages/</code>或<code>app/</code>统一管理路由
   * 动态路由参数应明确命名（如<code>[slug].js</code>而非<code>[id].js</code>）

2. '''组件分类''':
   * 通用组件放入<code>components/ui/</code>
   * 页面专用组件放入<code>components/pageName/</code>

3. '''样式管理''':
   * 全局样式在<code>_app.js</code>导入
   * CSS模块推荐命名：<code>ComponentName.module.css</code>

== 实际案例 ==

'''电商网站结构示例'''：

<syntaxhighlight lang="bash">
src/
├── app/
│   ├── (marketing)/       # 路由组
│   │   ├── page.js
│   │   └── layout.js
│   ├── cart/
│   │   └── page.js
│   └── products/
│       ├── [slug]/
│       │   ├── page.js
│       │   └── reviews.js # 路由片段
│       └── layout.js
├── components/
│   ├── cart/
│   │   └── AddToCart.js
│   └── products/
│       └── Price.js
└── lib/
    └── formatCurrency.js
</syntaxhighlight>

== 常见问题 ==

'''Q: 能否自定义pages目录路径？'''<br>
A: 可以，通过<code>next.config.js</code>的<code>pageExtensions</code>和自定义服务器配置实现，但会失去部分优化特性。

'''Q: App Router和Pages Router能混用吗？'''<br>
A: 可以，但推荐新项目使用App Router，迁移中的项目可逐步过渡。

'''Q: 如何组织大型项目的文件结构？'''<br>
A: 推荐按功能划分：
```bash
src/
├── features/
│   ├── auth/
│   ├── dashboard/
│   └── settings/
└── shared/
    ├── components/
    └── utils/
```

[[Category:后端框架]]
[[Category:Next.js]]
[[Category:Next.js基础]]