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

基本用法：

npx next [command] [options]

参考

以下选项可用：

命令

以下命令可用：

须知：不带命令运行 next 是 next dev 的别名。

next dev 选项

next dev 以开发模式启动应用程序，支持热模块重载 (HMR)、错误报告等。运行 next dev 时可用以下选项：

next build 选项

next build 创建应用程序的优化生产构建。输出显示每个路由的信息。例如：

Route (app)
┌ ○ /_not-found
└ ƒ /products/[id]

○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

以下选项可用于 next build 命令：

next start 选项

next start 以生产模式启动应用程序。应用程序应首先使用 next build 进行编译。

以下选项可用于 next start 命令：

next info 选项

next info 打印有关当前系统的相关详细信息，这些信息可用于在提交 GitHub issue 时报告 Next.js 错误。此信息包括操作系统平台/架构/版本、二进制文件（Node.js, npm, Yarn, pnpm）、包版本（next, react, react-dom）等。

输出应如下所示：

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.6.0
  Available memory (MB): 65536
  Available CPU cores: 10
Binaries:
  Node: 20.12.0
  npm: 10.5.0
  Yarn: 1.22.19
  pnpm: 9.6.0
Relevant Packages:
  next: 15.0.0-canary.115 // Latest available version is detected (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 命令：

next telemetry 选项

Next.js 收集关于一般使用情况的完全匿名遥测数据。参与此匿名计划是可选的，如果您不希望共享信息，可以选择退出。

以下选项可用于 next telemetry 命令：

了解更多关于 遥测 的信息。

next typegen 选项

next typegen 为应用程序的路由生成 TypeScript 定义，而无需执行完整构建。这对于 IDE 自动补全和 CI 路由使用类型检查非常有用。

以前，路由类型只在 next dev 或 next build 期间生成，这意味着直接运行 tsc --noEmit 将无法验证您的路由类型。现在您可以独立生成类型并进行外部验证：

# Generate route types first, then validate with TypeScript
next typegen && tsc --noEmit

# Or in CI workflows for type checking without building
next typegen && npm run type-check

以下选项可用于 next typegen 命令：

输出文件写入 <distDir>/types（通常是：.next/dev/types 或 .next/types，参见 isolatedDevBuild）：

next typegen
# or for a specific app
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 命令：

示例

调试预渲染错误

如果在 next build 期间遇到预渲染错误，您可以传递 --debug-prerender 标志以获取更详细的输出：

next build --debug-prerender

这将启用几个实验性选项，使调试更加容易：

• 禁用服务器代码压缩：
  • experimental.serverMinification = false
  • experimental.turbopackMinify = false
• 为服务器捆绑包生成源映射：
  • experimental.serverSourceMaps = true
• 启用用于预渲染的子进程中的源映射消耗：
  • enablePrerenderSourceMaps = true
• 即使在第一个预渲染错误之后也继续构建，以便您可以一次性查看所有问题：
  • experimental.prerenderEarlyExit = false

这有助于在构建输出中显示更易读的堆栈跟踪和代码帧。

警告：--debug-prerender 仅用于开发环境调试。请勿将使用 --debug-prerender 生成的构建部署到生产环境，因为它可能会影响性能。

构建特定路由

您可以使用 --debug-build-paths 选项在 App Router 和 Pages Router 中仅构建特定路由。这对于处理大型应用程序时的快速调试非常有用。--debug-build-paths 选项接受逗号分隔的文件路径并支持 glob 模式：

# Build a specific route
next build --debug-build-paths="app/page.tsx"

# Build more than one route
next build --debug-build-paths="app/page.tsx,pages/index.tsx"

# Use glob patterns
next build --debug-build-paths="app/**/page.tsx"
next build --debug-build-paths="pages/*.tsx"

更改默认端口

默认情况下，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 可以使用 --experimental-https 标志通过 next dev 生成自签名证书：

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.pem

next dev --experimental-https 仅用于开发目的，并使用 mkcert 创建本地受信任的证书。在生产环境中，请使用受信任机构正式颁发的证书。

配置下游代理的超时

将 Next.js 部署在下游代理（例如 AWS ELB/ALB 等负载均衡器）后面时，务必将 Next.js 底层的 HTTP 服务器配置为具有比下游代理超时时间_更长_的 keep-alive 超时。否则，一旦某个 TCP 连接达到 keep-alive 超时时间，Node.js 将立即终止该连接，而不会通知下游代理。这会导致代理在尝试重用已被 Node.js 终止的连接时出现代理错误。

要为生产 Next.js 服务器配置超时值，请将 --keepAliveTimeout（以毫秒为单位）传递给 next start，如下所示：

next start --keepAliveTimeout 70000

传递 Node.js 参数

您可以将任何 Node.js 参数 传递给 next 命令。例如：

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