NNext.js 中文网 GitHub

next CLI

了解如何使用 Next.js CLI 运行和构建你的应用程序。

Next.js CLI 允许你开发、构建、启动应用程序等。

基本用法:

bash · pnpm
pnpm next [command] [options]
bash · npm
npx next [command] [options]
bash · yarn
yarn next [command] [options]
bash · bun
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 为你的应用程序创建经过优化的生产构建。输出会显示每条路由的信息。例如:

Terminal
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)等。

输出应如下所示:

Terminal
操作系统:
  平台: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/A

next 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 不会验证你的路由类型。现在你可以独立生成类型并在外部验证它们:

Terminal
# 先生成路由类型,然后使用 TypeScript 验证
next typegen && tsc --noEmit

# 或在 CI 工作流中进行类型检查而无需构建
next typegen && npm run type-check

next typegen 命令可使用以下选项:

选项描述
-h, --help显示所有可用选项。
[directory]用于生成类型的目录。如果未提供,则使用当前目录。

输出文件写入 <distDir>/types(通常为 .next/types)。next dev 将其自身的类型写入 .next/dev/types。当没有 next dev 服务器运行时,next typegen 会移除 .next/dev/types,以避免已移动或已删除的路由类型导致类型检查失败。next dev 启动时会重新生成它们。

Terminal
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 和其他资源。此命令不会生成应用程序构建。

bash · pnpm
pnpm next analyze
bash · npm
npx next analyze
bash · yarn
yarn next analyze
bash · bun
bunx next analyze

默认情况下,该命令在分析完成后启动一个本地服务器,使你可以在浏览器中查看 bundle 组成。分析器可让你:

  • 按路由筛选 bundle,并在客户端和服务器视图之间切换
  • 查看完整的导入链,了解某个模块为何被包含
  • 追踪跨服务器到客户端组件边界以及动态导入的导入

有关优化策略,请参阅包打包。

要将分析输出写入磁盘而不启动服务器,请使用 --output。快照和交互式 UI 文件会写入 <distDir>/diagnostics/analyze(通常为 .next/diagnostics/analyze)。

Terminal
# 构建并保存快照,而不启动 UI 服务器
npx next analyze --output --snapshot audit-1

# 将保存的图以每行一个 JSON 对象的形式流式输出,无需重新构建
npx next analyze export --snapshot audit-1 > graph.jsonl

next 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 标志以获得更详细的输出:

Terminal
next build --debug-prerender

这会启用多个实验性选项,使调试更容易:

  • 禁用服务端代码压缩:
    • experimental.serverMinification = false
    • experimental.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 模式,并会排除任何以 ! 为前缀的路径:

Terminal
# 构建特定路由
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 选项更改默认端口,如下所示:

Terminal
next dev -p 4000

或者使用 PORT 环境变量:

Terminal
PORT=4000 next dev

小知识:PORT 无法在 .env 中设置,因为 HTTP 服务器的启动发生在任何其他代码初始化之前。

在开发中使用 HTTPS#

对于 webhook 或身份验证等特定用例,你可以使用 HTTPS 在 localhost 上获得安全的环境。Next.js 可以通过 next dev 使用 --experimental-https 标志生成自签名证书:

Terminal
next dev --experimental-https

使用生成的证书后,Next.js 开发服务器将运行在 https://localhost:3000。除非通过 -p、--port 或 PORT 指定端口,否则使用默认端口 3000。

你还可以使用 --experimental-https-key 和 --experimental-https-cert 提供自定义证书和密钥。此外,你也可以使用 --experimental-https-ca 提供自定义 CA 证书。

Terminal
next dev --experimental-https --experimental-https-key ./certificates/localhost-key.pem --experimental-https-cert ./certificates/localhost.pem

next 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,如下所示:

Terminal
next start --keepAliveTimeout 70000

传递 Node.js 参数#

你可以将任何 node 参数传递给 next 命令。例如:

Terminal
NODE_OPTIONS='--throw-deprecation' next
NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' next

CPU 性能分析#

你可以捕获 CPU 性能分析文件来分析 Next.js 应用程序中的性能瓶颈。--experimental-cpu-prof 标志会启用 V8 内置的 CPU 分析器,并在进程退出时将分析文件保存到 .next-profiles/:

Terminal
# 分析构建过程
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 选项以帮助调试预渲染错误。
Next.js 中文网