next 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 错误。此信息包括操作系统平台/架构/版本、二进制文件（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/types）

next typegen
# or for a specific app
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
• 为服务器捆绑包生成源映射
  • experimental.serverSourceMaps = true
• 在用于预渲染的子进程中启用源映射消费
  • enablePrerenderSourceMaps = true
• 即使在第一次预渲染错误后也继续构建，这样你就可以一次性看到所有问题
  • experimental.prerenderEarlyExit = false

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

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

构建特定路由

你可以使用 --debug-build-paths 选项在 App 和 Pages 路由中仅构建特定路由。这对于处理大型应用程序时加快调试速度非常有用。--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 时使用 https://: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://: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 的底层 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