Next.js Project Structure

Next.js项目结构

This page provides an overview of the file and folder structure of a Next.js project. It covers top-level files and folders, configuration files, and routing conventions within the app and pages directories.

本页面概述了Next.js项目的文件和文件夹结构，它涵盖了顶层文件和文件夹、配置文件以及在app和pages目录中的路由规则。

conventions: 公约

Top-level folders

顶层文件夹

名称 描述
app App Router
pages Pages Router
public Static assets to be served(待服务的静态资产)
src Optional application source folder(可选的应用程序源文件夹)

Top-level files

顶层文件

Next.js
next.config.js Configuration file for Next.js
package.json Project dependencies and scripts
instrumentation.ts OpenTelemetry and Instrumentation file(OpenTelemetry和仪表文件,todo不知道啥意思)
middleware.ts Next.js request middleware(Next.js请求中间件)
.env Environment variables
.env.local Local environment variables
.env.production Production environment variables
.env.development Development environment variables
.eslintrc.json Configuration file for ESLint
.gitignore Git files and folders to ignore
next-env.d.ts TypeScript declaration file for Next.js(Next.js的TypeScript声明文件)
tsconfig.json Configuration file for TypeScript
jsconfig.json Configuration file for JavaScript

middleware： 中间件

declaration：声明

app Routing Conventions

app路由规则

Routing Files

路由文件
layout .js .jsx .tsx Layout
page .js .jsx .tsx Page
loading .js .jsx .tsx Loading UI
not-found .js .jsx .tsx Not found UI
error .js .jsx .tsx Error UI
global-error .js .jsx .tsx Global error UI
route .js .ts API endpoint
template .js .jsx .tsx Re-rendered layout(重新渲染的布局)
default .js .jsx .tsx Parallel route fallback page

Nested Routes

嵌套路由
folder Route segment（路由段）
folder/folder Nested route segment（嵌套路由段）

Dynamic Routes

动态路由
[folder] Dynamic route segment
[...folder] Catch-all route segment
[[…folder]] Optional catch-all route segment

动态路由即是匹配路径作为参数，[folder]匹配单个路径：

Route Example URL params
app/blog/[slug]/page.js /blog/a { slug: 'a' }
app/blog/[slug]/page.js /blog/b { slug: 'b' }
app/blog/[slug]/page.js /blog/c { slug: 'c' }

[…folder]匹配多个路径：

Route Example URL params
app/shop/[...slug]/page.js /shop/a { slug: ['a'] }
app/shop/[...slug]/page.js /shop/a/b { slug: ['a', 'b'] }
app/shop/[...slug]/page.js /shop/a/b/c { slug: ['a', 'b', 'c'] }

[[…folder]]匹配零或多个路径：

Route Example URL params
app/shop/[[...slug]]/page.js /shop {}
app/shop/[[...slug]]/page.js /shop/a { slug: ['a'] }
app/shop/[[...slug]]/page.js /shop/a/b { slug: ['a', 'b'] }
app/shop/[[...slug]]/page.js /shop/a/b/c { slug: ['a', 'b', 'c'] }

Route Groups and Private Folders

路由组和私有文件夹
(folder) Group routes without affecting routing(在不影响路由选择的情况下分组路由)
_folder Opt folder and all child segments out of routing(选择将文件夹和所有子文件排除在路由选择之外)

路由组主要解决多个路由的不同布局问题。app路由只有个根布局，默认路由的布局都是使用它。这会带来一个问题：多个路由的布局不同时如何解决？路由组可以让不同组的布局分开，A组使用A组的布局，B组使用B组的布局。

私有文件主要解决让一些app目录下的文件不被路由，由于app路由存在文件夹就是路由路径的方式，反过来就是说所有文件夹都是路由路径，如果需要指定某些文件夹不加入路由，就可以在文件夹前加入_前缀，表示这个文件夹是私有的，不参与路由。

Parallel and Intercepted Routes

并行路由和拦截路由
@folder Named slot
(.)folder Intercept same level
(..)folder Intercept one level above
(..)(..)folder Intercept two levels above
(...)folder Intercept from root

并行路由可以在同一个页面下展示多种布局，比如做聚合页时，如何系统本身就有多个页面，那么只要使用并行路由将它们发一起即可。

拦截路由可以使一个页面在另一个页面上层展示，而不必跳转。比如在图片列表打开图片详情，图片详情直接悬浮在图片列表上。当然，图片详情页面也可以通过路由的方式和原来一样在新的页面打开。相当于一个页面的不同用法。

Metadata File Conventions

元数据文件规则

App Icons

App图标
favicon .ico Favicon file
icon .ico .jpg .jpeg .png .svg App Icon file
icon .js .ts .tsx Generated App Icon
apple-icon .jpg .jpeg, .png Apple App Icon file
apple-icon .js .ts .tsx Generated Apple App Icon

Open Graph and Twitter Images

Open Graph and Twitter 图片，用于社交媒体使用，分享网站时可以带上此类图片。
opengraph-image .jpg .jpeg .png .gif Open Graph image file
opengraph-image .js .ts .tsx Generated Open Graph image
twitter-image .jpg .jpeg .png .gif Twitter image file
twitter-image .js .ts .tsx Generated Twitter image

SEO
sitemap .xml Sitemap file
sitemap .js .ts Generated Sitemap
robots .txt Robots file
robots .js .ts Generated Robots file

pages Routing Conventions

Pages路由规则

Special Files
_app .js .jsx .tsx Custom App
_document .js .jsx .tsx Custom Document
_error .js .jsx .tsx Custom Error Page
404 .js .jsx .tsx 404 Error Page
500 .js .jsx .tsx 500 Error Page

Routes
Folder convention
index .js .jsx .tsx Home page
folder/index .js .jsx .tsx Nested page
File convention
index .js .jsx .tsx Home page
file .js .jsx .tsx Nested page

Dynamic Routes
Folder convention
[folder]/index .js .jsx .tsx Dynamic route segment
[...folder]/index .js .jsx .tsx Catch-all route segment
[[…folder]]/index .js .jsx .tsx Optional catch-all route segment
File convention
[file] .js .jsx .tsx Dynamic route segment
[...file] .js .jsx .tsx Catch-all route segment
[[…file]] .js .jsx .tsx Optional catch-all route segment