跳至内容
API 参考CLInext CLI

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显示所有可用选项。
[目录]构建应用程序的目录。如果未提供，则使用当前目录。
--turbo使用 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 <跟踪 URL>将调试跟踪的子集报告到远程 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启用更详细的构建输出。启用此标志后，将显示其他构建输出，例如重写、重定向和标头。
--profile启用生产环境下的 React 性能分析。
--no-lint禁用代码风格检查。
--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，环境变量：PORT）
-H 或 --hostname <hostname>指定启动应用程序的主机名（默认值：0.0.0.0）。
--keepAliveTimeout <keepAliveTimeout>指定在关闭非活动连接之前等待的最大毫秒数。

next info 选项

next info 打印有关当前系统的相关详细信息，这些信息可用于在打开 GitHub 问题 时报告 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 命令

选项描述
[目录]要对应用程序进行代码风格检查的基本目录。如果未提供，则将使用当前目录。
-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.js 在开发过程中以及使用 next start 时使用 https://127.0.0.1:3000。可以使用 -p 选项更改默认端口，如下所示

终端
next dev -p 4000

或使用 PORT 环境变量

终端
PORT=4000 next dev

**注意**：在启动 HTTP 服务器之前，会初始化任何其他代码，因此无法在 .env 中设置 PORT。

在开发过程中使用 HTTPS

对于某些用例（如 Webhook 或身份验证），您可以使用 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 时，将为您的 Next.js 应用程序 自动配置 HTTPS。

配置下游代理的超时

当 Next.js 部署在后端代理（例如 AWS ELB/ALB 等负载均衡器）后面时，务必将 Next.js 底层的 HTTP 服务器配置为使用保持活动超时，其值应大于后端代理的超时时间。否则，一旦某个 TCP 连接达到保持活动超时，Node.js 将立即终止该连接，而不会通知后端代理。这会导致代理错误，因为代理在尝试重用 Node.js 已经终止的连接时会失败。

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

终端
next start --keepAliveTimeout 70000

传递 Node.js 参数

您可以将任何Node.js 参数传递给 next 命令。例如

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