next CLI

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

基本用法

npx next [command] [options]

参考

以下选项可用

选项	描述
`-h` 或 `--help`	显示所有可用选项
`-v` 或 `--version`	输出 Next.js 版本号

命令

以下命令可用

命令	描述
`dev`	以开发模式启动 Next.js，支持热模块重载、错误报告等。
`build`	创建应用程序的优化生产构建。显示有关每个路由的信息。
`start`	以生产模式启动 Next.js。应用程序应首先使用 `next build` 进行编译。
`info`	打印有关当前系统的相关详细信息，可用于报告 Next.js 错误。
`telemetry`	允许你启用或禁用 Next.js 的完全匿名遥测数据收集。
`typegen`	无需运行完整的构建即可为路由、页面、布局和路由处理程序生成 TypeScript 定义。

须知：不带命令运行 next 等同于 next dev。

`next dev` 选项

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

选项	描述
`-h, --help`	显示所有可用选项。
`[目录]`	用于构建应用程序的目录。如果未提供，则使用当前目录。
`--turbopack`	强制启用 Turbopack（默认启用）。也可使用 `--turbo`。
`--webpack`	在开发过程中使用 Webpack 而不是默认的 Turbopack 打包器。
`-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。

`next build` 选项

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

Route (app)
┌ ○ /_not-found
└ ƒ /products/[id]
 
○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

next build 命令的以下选项可用

选项	描述
`-h, --help`	显示所有可用选项。
`[目录]`	用于构建应用程序的目录。如果未提供，则使用当前目录。
`--turbopack`	强制启用 Turbopack（默认启用）。也可使用 `--turbo`。
`--webpack`	使用 Webpack 构建。
`-d` 或 `--debug`	启用更详细的构建输出。启用此标志后，将显示重写、重定向和头部等额外的构建输出。

`--profile`	为 React 启用生产性能分析。
`--no-lint`	禁用 linting。注意：linting 将在 Next 16 中从 `next build` 中移除。如果你使用 Next 15.5+ 且使用 `eslint` 以外的 linter，构建期间将不会进行 linting。
`--no-mangling`	禁用名称混淆。这可能会影响性能，仅应用于调试目的。
`--experimental-app-only`	仅构建 App Router 路由。
`--experimental-build-mode [模式]`	使用实验性构建模式。（选项：“compile”、“generate”，默认值：“default”）
`--debug-prerender`	在开发环境中调试预渲染错误。
`--debug-build-paths=<patterns>`	仅构建特定路由以进行调试。

`next start` 选项

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

next start 命令的以下选项可用

选项	描述
`-h` 或 `--help`	显示所有可用选项。
`[目录]`	用于启动应用程序的目录。如果未提供目录，则使用当前目录。
`-p` 或 `--port <port>`	指定启动应用程序的端口号。（默认值：3000，环境变量：PORT）
`-H` 或 `--hostname <hostname>`	指定启动应用程序的主机名（默认值：0.0.0.0）。
`--keepAliveTimeout <keepAliveTimeout>`	指定关闭非活动连接前的最大等待毫秒数。

`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 命令的以下选项可用

选项	描述
`-h` 或 `--help`	显示所有可用选项
`--verbose`	收集更多信息以进行调试。

`next telemetry` 选项

Next.js 收集有关一般使用情况的完全匿名遥测数据。参与此匿名程序是可选的，如果你不愿意分享信息，可以选择退出。

next telemetry 命令的以下选项可用

选项	描述
`-h, --help`	显示所有可用选项。
`--enable`	启用 Next.js 的遥测数据收集。
`--disable`	禁用 Next.js 的遥测数据收集。

了解更多关于遥测。

`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 命令的以下选项可用

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

输出文件写入 <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 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 时使用 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.js 底层 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

版本	更改
`v16.0.0`	JS 包大小指标已从 `next build` 中移除。
`v15.5.0`	添加 `next typegen` 命令
`v15.4.0`	为 `next build` 添加 `--debug-prerender` 选项，以帮助调试预渲染错误。