Next.js CLI

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 bug。此信息包括操作系统平台/架构/版本、二进制文件（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 不会验证你的路由类型。现在你可以独立生成类型并在外部验证它们：

# 先生成路由类型，然后使用 TypeScript 验证
next typegen && tsc --noEmit
 
# 或在 CI 工作流中进行类型检查而不构建
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 typegen ./apps/web

值得注意的是：next typegen 使用生产构建阶段加载你的 Next.js 配置（next.config.js、next.config.mjs 或 next.config.ts）。确保所需的环境变量和依赖项可用，以便配置能够正确加载。

示例

调试预渲染错误

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

next build --debug-prerender

这会启用几个实验性选项以便更容易调试：

• 禁用服务器代码压缩：
  • experimental.serverMinification = false
  • experimental.turbopackMinify = false
• 为服务器包生成 source maps：
  • experimental.serverSourceMaps = true
• 在用于预渲染的子进程中启用 source map 消费：
  • enablePrerenderSourceMaps = true
• 即使在第一个预渲染错误后也继续构建，这样你可以一次看到所有问题：
  • experimental.prerenderEarlyExit = false

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

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

构建特定路由

你可以使用 --debug-build-paths 选项仅构建 App 和 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"
 
# 使用 glob 模式
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

对于某些用例，如 webhooks 或身份验证，你可以使用 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 创建本地受信任的证书。在生产环境中，请使用来自受信任机构的正式颁发证书。

为下游代理配置超时

在下游代理（例如负载均衡器如 AWS ELB/ALB）后面部署 Next.js 时，重要的是配置 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' next