创建新的 Next.js 应用
如何使用 create-next-app 创建新的 Next.js 应用。设置 TypeScript、ESLint,并配置 next.config.js 文件。
创建一个新的 Next.js 应用并在本地运行它。
快速开始#
- 创建一个名为
my-app的新 Next.js 应用 cd my-app并启动开发服务器。- 访问
http://localhost:3000。
pnpm create next-app@latest my-app --yes
cd my-app
pnpm devnpx create-next-app@latest my-app --yes
cd my-app
npm run devyarn create next-app@latest my-app --yes
cd my-app
yarn devbun create next-app@latest my-app --yes
cd my-app
bun dev--yes使用已保存的偏好设置或默认值跳过提示。默认设置会启用 TypeScript、Tailwind CSS、ESLint、App Router 和 Turbopack,使用导入别名@/*,并包含AGENTS.md以指导编码代理编写最新的 Next.js 代码。
系统要求#
在开始之前,请确保你的开发环境满足以下要求:
- 最低 Node.js 版本:20.9
- 操作系统:macOS、Windows(包括 WSL)和 Linux。
支持的浏览器#
Next.js 支持现代浏览器,无需任何配置。
- Chrome 111+
- Edge 111+
- Firefox 111+
- Safari 16.4+
了解更多关于浏览器支持的信息,包括如何配置 polyfill 和指定目标浏览器。
使用 CLI 创建#
创建新的 Next.js 应用最快的方法是使用 create-next-app,它会自动为你完成所有设置。要创建项目,请运行:
pnpm create next-appnpx create-next-app@latestyarn create next-appbun create next-app安装时,你会看到以下提示:
你的项目叫什么名字?my-app
是否使用推荐的 Next.js 默认配置?
是,使用推荐默认配置 - TypeScript、ESLint、不使用 React Compiler、Tailwind CSS、不使用 src/ 目录、Cache Components、AGENTS.md
否,复用之前的设置
否,自定义设置 - 选择你自己的偏好如果你选择“自定义设置”,你会看到以下提示:
你是否使用 TypeScript?否 / 是
你想使用哪个 linter?ESLint / Biome / 无
你是否使用 React Compiler?否 / 是
你是否使用 Tailwind CSS?否 / 是
你是否将代码放在 `src/` 目录中?否 / 是
你是否使用 Cache Components?否 / 是
你是否自定义导入别名(默认为 `@/*`)?否 / 是
你想配置什么导入别名?@/*
是否包含 AGENTS.md 以引导编程智能体编写最新的 Next.js 代码?否 / 是在提示完成后,create-next-app 将使用你的项目名称创建一个文件夹并安装所需的依赖项。
手动安装#
要手动创建新的 Next.js 应用,请安装所需的包:
pnpm i next@latest react@latest react-dom@latestnpm i next@latest react@latest react-dom@latestyarn add next@latest react@latest react-dom@latestbun add next@latest react@latest react-dom@latest小知识:
App Router内置使用了 React canary 版本,其中包含所有稳定的 React 19 更改,以及在框架中验证的更新功能,但你仍应在 package.json 中声明 react 和 react-dom,以确保工具和生态系统的兼容性。Pages Router使用package.json中的 React 版本。
然后,将以下脚本添加到你的 package.json 文件中:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "eslint",
"lint:fix": "eslint --fix"
}
}这些脚本对应于开发应用程序的不同阶段:
next dev:使用 Turbopack(默认打包工具)启动开发服务器。next build:为生产环境构建应用程序。next start:启动生产服务器。eslint:运行 ESLint。
Turbopack 现在是默认的打包工具。要使用 Webpack,请运行 next dev --webpack 或 next build --webpack。有关配置详情,请参阅 Turbopack 文档。
创建 app 目录#
Next.js 使用文件系统路由,这意味着应用程序中的路由由文件的组织方式决定。
创建一个 app 文件夹。然后,在 app 中创建一个 layout.tsx 文件。这个文件是根布局。它是必需的,并且必须包含 <html> 和 <body> 标签。
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}export default function RootLayout({ children }) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}创建一个主页 app/page.tsx,包含一些初始内容:
export default function Page() {
return <h1>Hello, Next.js!</h1>
}export default function Page() {
return <h1>Hello, Next.js!</h1>
}当用户访问你的应用程序根目录(/)时,layout.tsx 和 page.tsx 都会被渲染。
小知识:
- 如果你忘记创建根布局,Next.js 会在使用
next dev运行开发服务器时自动创建该文件。- 你可以选择在项目根目录使用
src文件夹,以将应用程序代码与配置文件分开。
创建 pages 目录#
Next.js 使用文件系统路由,这意味着应用程序中的路由由文件的组织方式决定。
在项目根目录创建一个 pages 目录。然后,在 pages 文件夹中添加一个 index.tsx 文件。这将是你的主页(/):
export default function Page() {
return <h1>Hello, Next.js!</h1>
}export default function Page() {
return <h1>Hello, Next.js!</h1>
}接下来,在 pages/ 中添加一个 _app.tsx 文件来定义全局布局。了解更多关于自定义 App 文件的信息。
import type { AppProps } from 'next/app'
export default function App({ Component, pageProps }: AppProps) {
return <Component {...pageProps} />
}export default function App({ Component, pageProps }) {
return <Component {...pageProps} />
}最后,在 pages/ 中添加一个 _document.tsx 文件来控制服务器的初始响应。了解更多关于自定义 Document 文件的信息。
import { Html, Head, Main, NextScript } from 'next/document'
export default function Document() {
return (
<Html>
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
)
}import { Html, Head, Main, NextScript } from 'next/document'
export default function Document() {
return (
<Html>
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
)
}创建 public 文件夹(可选)#
在项目根目录创建一个 public 文件夹,用于存储静态资源,如图片、字体等。public 中的文件随后可以通过你的代码从基础 URL(/)开始引用。
然后,你可以使用根路径(/)引用这些资源。例如,public/profile.png 可以引用为 /profile.png:
import Image from 'next/image'
export default function Page() {
return <Image src="/profile.png" alt="Profile" width={100} height={100} />
}import Image from 'next/image'
export default function Page() {
return <Image src="/profile.png" alt="Profile" width={100} height={100} />
}运行开发服务器#
- 运行
npm run dev启动开发服务器。 - 访问
http://localhost:3000查看你的应用程序。 - 编辑
app/page.tsxpages/index.tsx文件并保存,即可在浏览器中看到更新后的结果。
设置 TypeScript#
最低 TypeScript 版本:
v5.1.0
Next.js 内置了对 TypeScript 的支持。要向项目添加 TypeScript,请将文件重命名为 .ts / .tsx 并运行 next dev。Next.js 将自动安装必要的依赖项,并添加一个包含推荐配置选项的 tsconfig.json 文件。
IDE 插件#
Next.js 包含一个自定义的 TypeScript 插件和类型检查器,VSCode 和其他代码编辑器可以使用它们进行高级类型检查和自动补全。
你可以通过以下方式在 VS Code 中启用该插件:
- 打开命令面板(
Ctrl/⌘+Shift+P) - 搜索 "TypeScript: Select TypeScript Version"
- 选择 "Use Workspace Version"
有关更多信息,请参阅 TypeScript 参考页面。
设置你的编辑器#
App Router 按约定命名文件,如 page.tsx、layout.tsx 和 route.ts,因此你的编辑器很快就会充满同名的标签页。用其所在的文件夹标记每个标签页,例如 blog/[id],这样你就能区分它们。
在 VS Code 1.88+ 或 Cursor 中,将自定义编辑器标签添加到 .vscode/settings.json。标记两层文件夹深度可以防止像 blog/[id]/page.tsx 这样的动态路由全部折叠为相同的 [id] 标签:
{
"workbench.editor.customLabels.patterns": {
"**/app/**/page.tsx": "${dirname(1)}/${dirname} - page.tsx",
"**/app/**/layout.tsx": "${dirname(1)}/${dirname} - layout.tsx",
"**/app/**/loading.tsx": "${dirname(1)}/${dirname} - loading.tsx",
"**/app/**/error.tsx": "${dirname(1)}/${dirname} - error.tsx",
"**/app/**/not-found.tsx": "${dirname(1)}/${dirname} - not-found.tsx",
"**/app/**/template.tsx": "${dirname(1)}/${dirname} - template.tsx",
"**/app/**/default.tsx": "${dirname(1)}/${dirname} - default.tsx",
"**/app/**/route.ts": "${dirname(1)}/${dirname} - route.ts"
}
}或者复制这个提示,让你的编码代理进行设置:
Set up custom editor labels so my Next.js App Router files are easy to tell apart. Read https://nextjs.org/docs/app/getting-started/installation#set-up-your-editor and add the workbench.editor.customLabels.patterns config shown there to my .vscode/settings.json, creating the file if it doesn't exist. Adjust the labels to taste. If I use a different editor, apply the equivalent setting or tell me it's automatic, and leave my other settings untouched.小知识: JetBrains IDE(WebStorm、IntelliJ)会自动为同名文件显示其所在文件夹,因此无需设置。
设置代码检查#
Next.js 支持使用 ESLint 或 Biome 进行代码检查。选择一个检查器并通过 package.json 脚本直接运行它。
- 使用 ESLint(全面的规则):
{
"scripts": {
"lint": "eslint",
"lint:fix": "eslint --fix"
}
}- 或者使用 Biome(快速的检查器 + 格式化工具):
{
"scripts": {
"lint": "biome check",
"format": "biome format --write"
}
}如果你的项目之前使用 next lint,请使用 codemod 将脚本迁移到 ESLint CLI:
npx @next/codemod@canary next-lint-to-eslint-cli .如果你使用 ESLint,请创建一个显式配置(推荐 eslint.config.mjs)。ESLint 支持传统的 .eslintrc.* 和较新的 eslint.config.mjs 格式。有关推荐设置,请参阅 ESLint API 参考。
小知识:从 Next.js 16 开始,
next build不再自动运行代码检查器。相反,你可以通过 NPM 脚本运行检查器。
有关更多信息,请参阅 ESLint 插件页面。
设置绝对路径导入和模块路径别名#
Next.js 内置支持 tsconfig.json 和 jsconfig.json 文件的 "paths" 和 "baseUrl" 选项。
这些选项允许你将项目目录别名设置为绝对路径,使模块导入更容易、更清晰。例如:
// 之前
import { Button } from '../../../components/button'
// 之后
import { Button } from '@/components/button'要配置绝对路径导入,请在 tsconfig.json 或 jsconfig.json 文件中添加 baseUrl 配置选项。例如:
{
"compilerOptions": {
"baseUrl": "src/"
}
}除了配置 baseUrl 路径之外,你还可以使用 "paths" 选项来为模块路径设置"别名"。
例如,以下配置将 @/components/* 映射到 components/*:
{
"compilerOptions": {
"baseUrl": "src/",
"paths": {
"@/styles/*": ["styles/*"],
"@/components/*": ["components/*"]
}
}
}每个 "paths" 都相对于 baseUrl 的位置。
升级你的 Next.js 应用#
保持 Next.js 版本为最新。每个版本都会在新功能之外提供安全补丁、错误修复和性能优化,保持最新可使每次升级的改动都很小。运行 upgrade 命令:
pnpm next upgradenpx next upgradeyarn next upgradebunx next upgrade升级还会更新 next 包中位于 node_modules/next/dist/docs/ 的随附文档。新功能会附带其文档,现有页面也会吸收在此过程中发现的新指南和注意事项。然后,项目中的 AI 编码代理 会根据你安装的版本而不是其训练数据来工作。
要让编码代理执行并验证升级,请运行 npx next@canary upgrade --agent=latest。有关其他策略,请参阅使用编码代理升级。