next CLI

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

基本用法：

Terminal

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 <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 创建应用程序的优化生产构建。输出显示每个路由的信息。例如：

Terminal

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	禁用代码检查。
--no-mangling	禁用名称混淆。这可能会影响性能，应仅用于调试目的。
--experimental-app-only	仅构建 App 路由。
--experimental-build-mode [mode]	使用实验性构建模式。（选项："compile"、"generate"，默认："default"）
--debug-prerender	在开发中调试预渲染错误。

next start 选项

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

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

选项	描述
-h 或 --help	显示所有可用选项。
[directory]	启动应用程序的目录。如果未提供目录，将使用当前目录。
-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）等。

输出应如下所示：

Terminal

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]	要检查的应用程序的基础目录。如果未提供，将使用当前目录。
-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	自动修复代码检查问题。
--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 build 期间遇到预渲染错误，可以传递 --debug-prerender 标志以获得更详细的输出：

Terminal

next build --debug-prerender

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

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

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

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

更改默认端口

默认情况下，Next.js 在开发期间和 next start 时使用 http://localhost:3000。可以使用 -p 选项更改默认端口，如下所示：

Terminal

next dev -p 4000

或使用 PORT 环境变量：

Terminal

PORT=4000 next dev

提示：PORT 不能在 .env 中设置，因为启动 HTTP 服务器发生在任何其他代码初始化之前。

在开发期间使用 HTTPS

对于某些用例，如 webhook 或身份验证，你可以使用 HTTPS 在 localhost 上拥有安全环境。Next.js 可以使用 next dev 的 --experimental-https 标志生成自签名证书：

Terminal

next dev --experimental-https

使用生成的证书，Next.js 开发服务器将存在于 https://localhost:3000。除非使用 -p、--port 或 PORT 指定端口，否则使用默认端口 3000。

你还可以使用 --experimental-https-key 和 --experimental-https-cert 提供自定义证书和密钥。可选地，你还可以使用 --experimental-https-ca 提供自定义 CA 证书。

Terminal

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 服务器，该超时大于下游代理的超时。否则，一旦达到给定 TCP 连接的保持连接超时，Node.js 将立即终止该连接而不通知下游代理。这导致代理在尝试重用 Node.js 已经终止的连接时出现错误。

要配置生产 Next.js 服务器的超时值，将 --keepAliveTimeout（以毫秒为单位）传递给 next start，如下所示：

Terminal

next start --keepAliveTimeout 70000

传递 Node.js 参数

你可以将任何 node 参数 传递给 next 命令。例如：

Terminal

NODE_OPTIONS='--throw-deprecation' next
NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' next

版本	更改
v15.4.0	为 next build 添加 --debug-prerender 选项以帮助调试预渲染错误。