简介/入门指南/项目结构

Next.js 项目结构

本文档概述了 Next.js 项目的文件与文件夹结构，涵盖顶层文件与文件夹、配置文件，以及 app 和 pages 目录中的路由约定。

顶层文件夹


`app`	应用路由 (App Router)
`pages`	页面路由 (Pages Router)
`public`	待托管的静态资源
`src`	可选的应用程序源码目录

顶层文件


Next.js
`next.config.js`	Next.js 配置文件
`package.json`	项目依赖与脚本
`instrumentation.ts`	OpenTelemetry 与性能监控文件
`middleware.ts`	Next.js 请求中间件
`.env`	环境变量
`.env.local`	本地环境变量
`.env.production`	生产环境变量
`.env.development`	开发环境变量
`.eslintrc.json`	ESLint 配置文件
`.gitignore`	Git 忽略文件列表
`next-env.d.ts`	Next.js 的 TypeScript 声明文件
`tsconfig.json`	TypeScript 配置文件
`jsconfig.json`	JavaScript 配置文件

`app` 路由约定

路由文件


`layout`	`.js` `.jsx` `.tsx`	布局文件
`page`	`.js` `.jsx` `.tsx`	页面文件
`loading`	`.js` `.jsx` `.tsx`	加载状态 UI
`not-found`	`.js` `.jsx` `.tsx`	404 页面 UI
`error`	`.js` `.jsx` `.tsx`	错误页面 UI
`global-error`	`.js` `.jsx` `.tsx`	全局错误 UI
`route`	`.js` `.ts`	API 端点
`template`	`.js` `.jsx` `.tsx`	可重渲染的布局
`default`	`.js` `.jsx` `.tsx`	并行路由的备用页面

嵌套路由


`folder`	路由片段
`folder/folder`	嵌套路由片段

动态路由


`[folder]`	动态路由片段
`[...folder]`	全捕获路由片段
`[[...folder]]`	可选全捕获路由片段

路由组与私有文件夹


`(folder)`	不影响路由的分组文件夹
`_folder`	将文件夹及其子片段排除在路由系统外

并行与拦截路由


`@folder`	命名插槽
`(.)folder`	拦截同级路由
`(..)folder`	拦截上一级路由
`(..)(..)folder`	拦截上两级路由
`(...)folder`	从根目录拦截路由

元数据文件约定

应用图标


`favicon`	`.ico`	网站图标文件
`icon`	`.ico` `.jpg` `.jpeg` `.png` `.svg`	应用图标文件
`icon`	`.js` `.ts` `.tsx`	动态生成的应用图标
`apple-icon`	`.jpg` `.jpeg`, `.png`	Apple 应用图标文件
`apple-icon`	`.js` `.ts` `.tsx`	动态生成的 Apple 应用图标

Open Graph 与 Twitter 图片


`opengraph-image`	`.jpg` `.jpeg` `.png` `.gif`	Open Graph 图片文件
`opengraph-image`	`.js` `.ts` `.tsx`	动态生成的 Open Graph 图片
`twitter-image`	`.jpg` `.jpeg` `.png` `.gif`	Twitter 图片文件
`twitter-image`	`.js` `.ts` `.tsx`	动态生成的 Twitter 图片

SEO


`sitemap`	`.xml`	站点地图文件
`sitemap`	`.js` `.ts`	动态生成的站点地图
`robots`	`.txt`	Robots 文件
`robots`	`.js` `.ts`	动态生成的 Robots 文件

`pages` 路由约定

特殊文件


`_app`	`.js` `.jsx` `.tsx`	自定义 App
`_document`	`.js` `.jsx` `.tsx`	自定义 Document
`_error`	`.js` `.jsx` `.tsx`	自定义错误页面
`404`	`.js` `.jsx` `.tsx`	404 错误页面
`500`	`.js` `.jsx` `.tsx`	500 错误页面

路由


文件夹约定
`index`	`.js` `.jsx` `.tsx`	首页
`folder/index`	`.js` `.jsx` `.tsx`	嵌套页面
文件约定
`index`	`.js` `.jsx` `.tsx`	首页
`file`	`.js` `.jsx` `.tsx`	嵌套页面

动态路由


文件夹约定
`[folder]/index`	`.js` `.jsx` `.tsx`	动态路由片段
`[...folder]/index`	`.js` `.jsx` `.tsx`	全捕获路由片段
`[[...folder]]/index`	`.js` `.jsx` `.tsx`	可选全捕获路由片段
文件约定
`[file]`	`.js` `.jsx` `.tsx`	动态路由片段
`[...file]`	`.js` `.jsx` `.tsx`	全捕获路由片段
`[[...file]]`	`.js` `.jsx` `.tsx`	可选全捕获路由片段

安装指南

使用 `create-next-app` 创建新的 Next.js 应用。配置 TypeScript、样式以及 `next.config.js` 文件。

构建应用

学习如何使用 Next.js 功能来构建您的应用程序。