next CLI
了解如何使用 Next.js CLI 运行和构建你的应用。
Next.js CLI 允许你开发、构建、启动应用程序等。
基本用法:
pnpm next [command] [options]npx next [command] [options]yarn next [command] [options]bunx next [command] [options]小知识:使用
npm run时,在 CLI 标志前使用--,以便 npm 将它们转发给next。pnpm、yarn或bun无需这样做。
参考#
以下选项可用:
| 选项 | 描述 |
|---|---|
-h 或 --help | 显示所有可用选项 |
-v 或 --version | 输出 Next.js 版本号 |
命令#
以下命令可用:
| 命令 | 描述 |
|---|---|
dev | 以开发模式启动 Next.js,提供热模块重载(Hot Module Reloading)、错误报告等功能。 |
build | 为你的应用程序创建经过优化的生产构建。显示每条路由的信息。 |
start | 以生产模式启动 Next.js。应用程序应先用 next build 编译。 |
info | 打印有关当前系统的相关详细信息,可用于报告 Next.js bug。 |
telemetry | 允许你启用或禁用 Next.js 完全匿名的遥测(telemetry)收集。 |
typegen | 为路由、页面、布局和路由处理器生成 TypeScript 定义,而无需运行完整构建。 |
upgrade | 将你的 Next.js 应用程序升级到最新版本。 |
analyze | 使用 Turbopack 分析 bundle 输出。不会生成构建产物。 |
小知识:不带命令运行
next是next dev的别名。
next dev 选项#
next dev 以开发模式启动应用程序,提供热模块重载(HMR)、错误报告等功能。
小知识:开发构建输出到
.next/dev而不是.next。这使你可以同时运行next dev和next build而不会发生冲突。
运行 next dev 时可使用以下选项:
| 选项 | 描述 |
|---|---|
-h, --help | 显示所有可用选项。 |
[directory] | 用于构建应用程序的目录。如果未提供,则使用当前目录。 |
--turbopack | 强制启用 Turbopack(默认启用)。也可用 --turbo。 |
--webpack | 开发时使用内置的 Webpack 代替默认的 Turbopack 打包器。 |
--custom-webpack | 开发时使用项目安装的 webpack。 |
-p 或 --port <port> | 指定启动应用程序的端口号。默认值:3000,环境变量:PORT |
-H 或 --hostname <hostname> | 指定启动应用程序的主机名。用于让网络中的其他设备也能访问该应用程序。默认值:0.0.0.0 |
--experimental-https | 使用 HTTPS 启动服务器并生成自签名证书。 |
--experimental-https-key <path> | HTTPS 密钥文件的路径。 |
--experimental-https-cert <path> | HTTPS 证书文件的路径。 |
--experimental-https-ca <path> | HTTPS 证书颁发机构文件的路径。 |
--experimental-upload-trace <traceUrl> | 将调试跟踪信息的一部分报告给远程 HTTP URL。 |
--experimental-cpu-prof | 使用 V8 的检查器启用 CPU 性能分析。分析文件会在退出时保存到 .next-profiles/。 |
next build 选项#
next build 为你的应用程序创建经过优化的生产构建。输出会显示每条路由的信息。例如:
Route (app)
┌ ○ /_not-found
└ ƒ /products/[id]
○ (Static) 预渲染为静态内容
ƒ (Dynamic) 按需进行服务端渲染请参阅构建指南以了解如何读取输出、预渲染动态路由以及调试构建错误。
next build 命令可使用以下选项:
| 选项 | 描述 |
|---|---|
-h, --help | 显示所有可用选项。 |
[directory] | 用于构建应用程序的目录。如果未提供,则使用当前目录。 |
--turbopack | 强制启用 Turbopack(默认启用)。也可用 --turbo。 |
--webpack | 使用内置的 Webpack 构建。 |
--custom-webpack | 使用项目安装的 webpack构建。 |
--analyze | 在 Turbopack 构建期间为交互式分析器生成 bundle 分析数据。 |
-d 或 --debug | 启用更详细的构建输出。启用此标志后,将显示额外的构建输出,如 rewrites、redirects 和 headers。 |
--profile | 启用生产环境的 React 性能分析。 |
--no-mangling | 禁用名称混淆(mangling)。这可能会影响性能,仅应用于调试目的。 |
--experimental-app-only | 仅构建 App Router 路由。 |
--experimental-build-mode [mode] | 使用实验性构建模式。(选项:"compile"、"generate",默认值:"default") |
--debug-prerender | 在开发中调试预渲染错误。 |
--debug-build-paths=<patterns> | 仅为调试构建特定路由。 |
--experimental-cpu-prof | 使用 V8 的检查器启用 CPU 性能分析。分析文件会在退出时保存到 .next-profiles/。 |
next start 选项#
next start 以生产模式启动应用程序。应用程序应先用 next build 编译。
next start 命令可使用以下选项:
| 选项 | 描述 |
|---|---|
-h 或 --help | 显示所有可用选项。 |
[directory] | 用于启动应用程序的目录。如果未提供目录,则使用当前目录。 |
-p 或 --port <port> | 指定启动应用程序的端口号。(默认值:3000,环境变量:PORT) |
-H 或 --hostname <hostname> | 指定启动应用程序的主机名(默认值:0.0.0.0)。 |
--keepAliveTimeout <keepAliveTimeout> | 指定关闭非活动连接前等待的最大毫秒数。 |
--experimental-cpu-prof | 使用 V8 的检查器启用 CPU 性能分析。分析文件会在退出时保存到 .next-profiles/。 |
next info 选项#
next info 打印有关当前系统的相关详细信息,可在提交 GitHub issue 时用于报告 Next.js bug。这些信息包括操作系统平台/架构/版本、二进制文件(Node.js、npm、Yarn、pnpm)、包版本(next、react、react-dom)等。
输出应如下所示:
操作系统:
平台:darwin
架构:arm64
版本:Darwin Kernel Version 23.6.0
可用内存(MB):65536
可用 CPU 核心数:10
二进制文件:
Node:20.12.0
npm:10.5.0
Yarn:1.22.19
pnpm:9.6.0
相关包:
next: 15.0.0-canary.115 // 检测到最新可用版本(15.0.0-canary.115)。
eslint-config-next: 14.2.5
react: 19.0.0-rc
react-dom: 19.0.0
typescript: 5.5.4
Next.js Config:
output: N/Anext info 命令可使用以下选项:
| 选项 | 描述 |
|---|---|
-h 或 --help | 显示所有可用选项 |
--verbose | 收集用于调试的额外信息。 |
next telemetry 选项#
Next.js 会收集有关一般使用情况的完全匿名遥测数据。参与此匿名计划是可选的,如果你不希望分享信息,可以选择退出。
next telemetry 命令可使用以下选项:
| 选项 | 描述 |
|---|---|
-h, --help | 显示所有可用选项。 |
--enable | 启用 Next.js 的遥测收集。 |
--disable | 禁用 Next.js 的遥测收集。 |
了解更多关于 Telemetry 的信息。
next typegen 选项#
next typegen 为你的应用程序路由生成 TypeScript 定义,而无需执行完整构建。这对于 IDE 自动补全和路由使用的 CI 类型检查很有用。
以前,路由类型仅在 next dev 或 next build 期间生成,这意味着直接运行 tsc --noEmit 不会验证你的路由类型。现在你可以独立生成类型并在外部验证它们:
# 先生成路由类型,然后使用 TypeScript 验证
next typegen && tsc --noEmit
# 或在 CI 工作流中进行类型检查而无需构建
next typegen && npm run type-checknext typegen 命令可使用以下选项:
| 选项 | 描述 |
|---|---|
-h, --help | 显示所有可用选项。 |
[directory] | 用于生成类型的目录。如果未提供,则使用当前目录。 |
输出文件写入 <distDir>/types(通常为 .next/types)。next dev 将其自身的类型写入 .next/dev/types。当没有 next dev 服务器运行时,next typegen 会移除 .next/dev/types,以避免已移动或已删除的路由类型导致类型检查失败。next dev 启动时会重新生成它们。
next typegen
# 或针对特定应用
next typegen ./apps/web此外,next typegen 会生成一个 next-env.d.ts 文件。我们建议将 next-env.d.ts 添加到你的 .gitignore 文件中。
next-env.d.ts 文件会被包含到你的 tsconfig.json 文件中,以使 Next.js 类型对你的项目可用。
要确保类型检查前存在 next-env.d.ts,请运行 next typegen。next dev 和 next build 命令也会生成 next-env.d.ts 文件,但仅为类型检查而运行这些命令通常并不可取,例如在 CI/CD 环境中。
小知识:
next typegen使用生产构建阶段加载你的 Next.js 配置(next.config.js、next.config.mjs或next.config.ts)。确保所需的环境变量和依赖项可用,以便配置能够正确加载。
next upgrade 选项#
next upgrade 将你的 Next.js 应用程序升级到最新版本。
next upgrade 命令可使用以下选项:
| 选项 | 描述 |
|---|---|
-h, --help | 显示所有可用选项。 |
[directory] | 包含要升级的 Next.js 应用程序的目录。如果未提供,则使用当前目录。 |
--revision <revision> | 指定要升级到的 Next.js 版本或标签(例如 latest、canary、15.0.0)。默认为你当前安装的发布渠道。 |
--verbose | 在升级过程中显示详细输出。 |
--agent [type] | 使用 security、latest 或 experimental-future 进行使用编码代理升级。默认为 experimental.agentUpgrade,或 security。不能与 --revision 组合使用。 |
next analyze 选项#
next analyze 使用 Turbopack 分析你的应用程序的 bundle 输出。此命令可帮助你了解 bundle 的大小和组成,包括 JavaScript、CSS 和其他资源。此命令不会生成应用程序构建。
pnpm next analyzenpx next analyzeyarn next analyzebunx next analyze默认情况下,该命令在分析完成后启动一个本地服务器,使你可以在浏览器中查看 bundle 组成。分析器可让你:
- 按路由筛选 bundle,并在客户端和服务器视图之间切换
- 查看完整的导入链,了解某个模块为何被包含
- 追踪跨服务器到客户端组件边界以及动态导入的导入
有关优化策略,请参阅包打包。
要将分析输出写入磁盘而不启动服务器,请使用 --output。快照和交互式 UI 文件会写入 <distDir>/diagnostics/analyze(通常为 .next/diagnostics/analyze)。
# 构建并保存快照,而不启动 UI 服务器
npx next analyze --output --snapshot audit-1
# 将保存的图以每行一个 JSON 对象的形式流式输出,无需重新构建
npx next analyze export --snapshot audit-1 > graph.jsonlnext analyze 命令可使用以下选项:
| 选项 | 描述 |
|---|---|
-h, --help | 显示所有可用选项。 |
[directory] | 用于分析应用程序的目录。如果未提供,则使用当前目录。 |
--no-mangling | 禁用名称混淆(mangling)。这可能会影响性能,仅应用于调试目的。 |
--profile | 启用生产环境的 React 性能分析。这可能会影响性能。 |
-o, --output | 构建并将二进制分析器数据和 UI 文件保存到 <distDir>/diagnostics/analyze,而不提供访问服务。 |
--snapshot <name> | 保存一个命名快照,替换同名的较早捕获。 |
--port <port> | 指定用于提供分析器访问的端口号。(默认值:4000,环境变量:PORT) |
next analyze export 选项#
export 子命令将现有快照以一系列 JSON Lines 的形式流式输出。它本身不运行分析,也不启动 Web UI。
| 选项 | 描述 |
|---|---|
-h, --help | 显示所有可用的导出选项。 |
[directory] | 包含已保存分析结果的应用程序目录。默认为当前目录。 |
--snapshot <name> | 按名称选择已保存的快照。默认为最新的保留快照。 |
--route <route> | 将导出限制为一条路由(仍包含完整的模块图)。 |
--dist-dir <directory> | 选择一个显式的相对或绝对构建目录,而不读取 next.config。 |
示例#
调试预渲染错误#
如果在 next build 期间遇到预渲染错误,可以传入 --debug-prerender 标志以获得更详细的输出:
next build --debug-prerender这会启用多个实验性选项,使调试更容易:
- 禁用服务端代码压缩:
experimental.serverMinification = falseexperimental.turbopackMinify = false
- 为服务端 bundle 生成 source maps:
experimental.serverSourceMaps = true
- 即使在第一个预渲染错误之后也继续构建,以便一次查看所有问题:
experimental.prerenderEarlyExit = false
这有助于在构建输出中显示更易读的堆栈跟踪和代码框架。
警告:
--debug-prerender仅用于开发中的调试。请勿将使用--debug-prerender生成的构建部署到生产环境,因为它可能会影响性能。
构建特定路由#
你可以使用 --debug-build-paths 选项仅构建 App Router 和 Pages Router 中的特定路由。这在处理大型应用程序时有助于更快地进行调试。--debug-build-paths 选项接受以逗号分隔的文件路径,支持 glob 模式,并会排除任何以 ! 为前缀的路径:
# 构建特定路由
next build --debug-build-paths="app/page.tsx"
# 构建多个路由
next build --debug-build-paths="app/page.tsx,pages/index.tsx"
# 在路径中包含路由组文件夹
next build --debug-build-paths="app/(marketing)/about/page.tsx"
# 使用 glob 模式
next build --debug-build-paths="app/**/page.tsx"
next build --debug-build-paths="pages/*.tsx"
# 排除带 ! 前缀的路由
next build --debug-build-paths="app/**/page.tsx,!app/admin/**"你可以将 --debug-build-paths 与 --debug-prerender 结合使用,以获得更详细的预渲染诊断。
在将路由放在 src/ 下的项目中,带或不带 src/ 前缀的路径都能解析,因此 app/page.tsx 和 src/app/page.tsx 都匹配同一条路由。
只有匹配的路由会出现在路由表中。当你选择一条 App Router 路由时,Next.js 还会包含内置的 /_not-found 路由。
更改默认端口#
默认情况下,Next.js 在开发期间和使用 next start 时使用 http://localhost:3000。可以使用 -p 选项更改默认端口,如下所示:
next dev -p 4000或者使用 PORT 环境变量:
PORT=4000 next dev小知识:
PORT无法在.env中设置,因为 HTTP 服务器的启动发生在任何其他代码初始化之前。
在开发中使用 HTTPS#
对于 webhook 或身份验证等特定用例,你可以使用 HTTPS 在 localhost 上获得安全的环境。Next.js 可以通过 next dev 使用 --experimental-https 标志生成自签名证书:
next dev --experimental-https使用生成的证书后,Next.js 开发服务器将运行在 https://localhost:3000。除非通过 -p、--port 或 PORT 指定端口,否则使用默认端口 3000。
你还可以使用 --experimental-https-key 和 --experimental-https-cert 提供自定义证书和密钥。此外,你也可以使用 --experimental-https-ca 提供自定义 CA 证书。
next dev --experimental-https --experimental-https-key ./certificates/localhost-key.pem --experimental-https-cert ./certificates/localhost.pemnext dev --experimental-https 仅用于开发,并使用 mkcert 创建本地受信任的证书。在生产环境中,请使用由受信任机构正确签发的证书。
为下游代理配置超时#
在将 Next.js 部署到下游代理(例如 AWS ELB/ALB 之类的负载均衡器)之后时,重要的是为 Next 底层的 HTTP 服务器配置keep-alive 超时,使其大于下游代理的超时时间。否则,一旦某个 TCP 连接达到 keep-alive 超时,Node.js 将立即终止该连接,而不会通知下游代理。当下游代理尝试重用 Node.js 已终止的连接时,就会导致代理错误。
要为生产环境的 Next.js 服务器配置超时值,请将 --keepAliveTimeout(以毫秒为单位)传递给 next start,如下所示:
next start --keepAliveTimeout 70000传递 Node.js 参数#
你可以将任何 node 参数传递给 next 命令。例如:
NODE_OPTIONS='--throw-deprecation' next
NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' nextCPU 性能分析#
你可以捕获 CPU 性能分析文件来分析 Next.js 应用程序中的性能瓶颈。--experimental-cpu-prof 标志会启用 V8 内置的 CPU 分析器,并在进程退出时将分析文件保存到 .next-profiles/:
# 分析构建过程
next build --experimental-cpu-prof
# 分析开发服务器(分析文件在 Ctrl+C 或 SIGTERM 时保存)
next dev --experimental-cpu-prof
# 分析生产服务器
next start --experimental-cpu-prof生成的 .cpuprofile 文件可以在 Chrome DevTools(Performance 标签页 → Load profile)或其他兼容 V8 的分析工具中打开。
小知识:分析文件以描述性前缀和时间戳命名。生成的分析文件取决于具体命令:
next dev:
dev-main-*- 父进程(开发服务器编排)dev-server-*- 子服务器进程(请求处理和渲染)- 这通常是你想要分析的对象
next build(Turbopack):
build-main-*- 主构建编排进程build-turbopack-*- Turbopack 编译工作进程
next build(Webpack):
build-main-*- 主构建编排进程build-webpack-client-*- 客户端 bundle 编译工作进程build-webpack-server-*- 服务端 bundle 编译工作进程build-webpack-edge-server-*- Edge runtime 编译工作进程
next start:
start-main-*- 生产服务器进程
| 版本 | 更改 |
|---|---|
v16.4.0 | 添加 next analyze export 命令。 |
v16.1.0 | 添加 next upgrade 命令 |
v16.1.0 | 添加 next experimental-analyze 命令 |
v16.0.0 | 从 next build 中移除了 JS bundle 大小指标 |
v15.5.0 | 添加 next typegen 命令 |
v15.4.0 | 为 next build 添加 --debug-prerender 选项以帮助调试预渲染错误。 |