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`	显示所有可用选项。
`[目录]`	用于构建应用程序的目录。如果未提供，则使用当前目录。
`--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

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

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

以下是 next build 命令的可用选项

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

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

`next start` 选项

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

以下是 next start 命令的可用选项

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

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

以下是 next lint 命令的可用选项

选项	描述
`[目录]`	要对其应用程序进行 linting 的基本目录。如果未提供，将使用当前目录。
`-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 时使用 https://127.0.0.1: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://127.0.0.1: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 时，重要的是为 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