logoNext.js 简体中文
文档博客学习
简介/API 参考文档/命令行工具 (CLI)/next 命令行工具 (CLI)

next 命令行工具 (CLI)

Next.js CLI 允许您开发、构建、启动应用程序以及执行更多操作。

基本用法：

终端
npx next [命令] [选项]

参考

以下是可用的选项：

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

命令

以下是可用的命令：

命令描述
dev以开发模式启动 Next.js，支持热模块替换 (HMR)、错误报告等功能。
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 为您的应用程序创建优化的生产构建。输出会显示每个路由的信息。例如：

终端
路由 (app)                             大小     首次加载 JS
┌ ○ /_not-found                          0 B               0 kB
└ ƒ /products/[id]                       0 B               0 kB

○  (静态)   预渲染为静态内容
ƒ  (动态)  按需服务器渲染
  • 大小：在客户端导航到页面时下载的资源大小。每个路由的大小仅包括其依赖项。
  • 首次加载 JS：从服务器访问页面时下载的资源大小。所有页面共享的 JS 量会单独显示为一个指标。

这两个值都是 使用 gzip 压缩 后的。首次加载指标会以绿色、黄色或红色显示。建议保持绿色以获得高性能的应用程序。

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

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

输出示例如下：

终端
操作系统：
  平台：darwin
  架构：arm64
  版本：Darwin Kernel Version 23.6.0
  可用内存 (MB)：65536
  可用 CPU 核心数：10
二进制文件：
  Node：20.12.0
  npm：10.5.0
  Yarn：1.22.19
  pnpm：9.6.0
相关包：
  next：15.0.0-canary.115 // 检测到最新可用版本 (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 配置：
  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.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.js 底层 HTTP 服务器的 keep-alive 超时 配置为 大于 下游代理的超时时间。否则，一旦某个 TCP 连接达到 keep-alive 超时时间，Node.js 会立即终止该连接而不通知下游代理。这将导致代理尝试复用已被 Node.js 终止的连接时出现错误。

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

Terminal
next start --keepAliveTimeout 70000

传递 Node.js 参数

可以向 next 命令传递任何 Node 参数。例如：

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

create-next-app 命令行工具

使用 create-next-app 命令行工具，只需一条命令即可创建 Next.js 应用。

架构

Next.js 工作原理

On this page