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 错误。
`lint`	为 `/src`、`/app`、`/pages`、`/components` 和 `/lib` 目录中的所有文件运行 ESLint。如果你的应用程序中尚未配置 ESLint，它还提供引导式设置来安装任何必需的依赖项。
`telemetry`	允许你启用或禁用 Next.js 的完全匿名遥测收集。

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

`next dev` 选项

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

选项	描述
`-h, --help`	显示所有可用选项。
`[directory]`	用于构建应用程序的目录。如果未提供，则使用当前目录。
`--turbopack`	使用 Turbopack 启动开发模式。
`-p` 或 `--port <端口号>`	指定启动应用程序的端口号。默认值：3000，环境变量：PORT
`-H` 或 `--hostname <主机名>`	指定启动应用程序的主机名。用于使应用程序可供网络上的其他设备访问。默认值：0.0.0.0
`--experimental-https`	使用 HTTPS 启动服务器并生成自签名证书。
`--experimental-https-key <路径>`	HTTPS 密钥文件的路径。
`--experimental-https-cert <路径>`	HTTPS 证书文件的路径。
`--experimental-https-ca <路径>`	HTTPS 证书颁发机构文件的路径。
`--experimental-upload-trace <traceUrl>`	将调试跟踪的子集报告给远程 HTTP URL。

`next build` 选项

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

终端

Route (app)                              Size     First Load JS
┌ ○ /_not-found                          0 B               0 kB
└ ƒ /products/[id]                       0 B               0 kB
 
○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

Size：客户端导航到页面时下载的资源大小。每个路由的大小仅包括其依赖项。
First Load JS：从服务器访问页面时下载的资源大小。所有页面共享的 JS 量显示为一个单独的指标。

这些值都 使用 gzip 压缩。首次加载用绿色、黄色或红色指示。目标是绿色以获得高性能应用程序。

以下选项适用于 next build 命令

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

`--profile`	启用生产环境 React 性能分析。
`--no-lint`	禁用 linting。
`--no-mangling`	禁用 mangling。这可能会影响性能，应仅用于调试目的。
`--experimental-app-only`	仅构建 App Router 路由。
`--experimental-build-mode [mode]`	使用实验性构建模式。（选项："compile"、"generate"，默认值："default"）

`next start` 选项

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

以下选项适用于 next start 命令

选项	描述
`-h` 或 `--help`	显示所有可用选项。
`[directory]`	用于启动应用程序的目录。如果未提供目录，则使用当前目录。
`-p` 或 `--port <端口号>`	指定启动应用程序的端口号。（默认值：3000，环境变量：PORT）
`-H` 或 `--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 lint` 选项

next lint 为 pages/、app/、components/、lib/ 和 src/ 目录中的所有文件运行 ESLint。如果你的应用程序中尚未配置 ESLint，它还提供引导式设置来安装任何必需的依赖项。

以下选项适用于 next lint 命令

选项	描述
`[directory]`	用于 lint 应用程序的基本目录。如果未提供，则使用当前目录。
`-d, --dir, <dirs...>`	包含要运行 ESLint 的目录或多个目录。
`--file, <files...>`	包含要运行 ESLint 的文件或多个文件。
`--ext, [exts...]`	指定 JavaScript 文件扩展名。（默认值：[".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx"]）
`-c, --config, <config>`	使用此配置文件，覆盖所有其他配置选项。
`--resolve-plugins-relative-to, <rprt>`	指定应从中解析插件的目录。
`--strict`	使用 Next.js 严格配置创建 `.eslintrc.json` 文件。
`--rulesdir, <rulesdir...>`	使用来自此目录的附加规则。
`--fix`	自动修复 linting 问题。
`--fix-type <fixType>`	指定要应用的修复类型（例如，problem、suggestion、layout）。
`--ignore-path <path>`	指定要忽略的文件。
`--no-ignore <path>`	禁用 `--ignore-path` 选项。
`--quiet`	仅报告错误。
`--max-warnings [maxWarnings]`	指定触发非零退出代码之前的警告数。（默认值：-1）
`-o, --output-file, <outputFile>`	指定要将报告写入的文件。
`-f, --format, <format>`	使用特定的输出格式。
`--no-inline-config`	防止注释更改配置或规则。
`--report-unused-disable-directives-severity <level>`	指定未使用 eslint-disable 指令的严重级别。（选项："error"、"off"、"warn"）
`--no-cache`	禁用缓存。
`--cache-location, <cacheLocation>`	指定缓存的位置。
`--cache-strategy, [cacheStrategy]`	指定用于检测缓存中已更改文件的策略。（默认值："metadata"）
`--error-on-unmatched-pattern`	当任何文件模式不匹配时报告错误。
`-h, --help`	显示此消息。

`next telemetry` 选项

Next.js 收集关于一般用法的完全匿名的遥测数据。参与此匿名计划是可选的，如果你不想分享信息，可以选择退出。

以下选项适用于 next telemetry 命令

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

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

示例

更改默认端口

默认情况下，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 创建本地信任的证书。在生产环境中，请使用来自受信任机构正确颁发的证书。

须知：当部署到 Vercel 时，HTTPS 将为你的 Next.js 应用程序自动配置。

配置下游代理的超时

当在下游代理（例如 AWS ELB/ALB 等负载均衡器）后面部署 Next.js 时，务必使用 keep-alive 超时配置 Next 的底层 HTTP 服务器，该超时大于下游代理的超时。否则，一旦给定 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