Menu

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)   预渲染为静态内容
ƒ  (Dynamic)  按需服务端渲染
  • Size：客户端导航到页面时下载的资源大小。每个路由的大小仅包含其依赖项。
  • First Load JS：从服务器访问页面时下载的资源大小。所有页面共享的 JS 数量作为单独的指标显示。

这两个值都经过了 gzip 压缩。首次加载由绿色、黄色或红色表示。为了获得良好的性能，应该以绿色为目标。

next build 命令可用的选项如下：

选项描述
-h, --help显示所有可用选项。
[directory]用于构建应用的目录。如果未提供，则使用当前目录。
-d 或 --debug启用更详细的构建输出。启用此标志后，将显示额外的构建输出，如重写、重定向和 header 信息。
--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 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 // 检测到最新可用版本 (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.js 在开发时和使用 next start 时使用 http://localhost:3000。可以使用 -p 选项更改默认端口，如下所示：

Terminal
next dev -p 4000

或使用 PORT 环境变量：

Terminal
PORT=4000 next dev

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

在开发时使用 HTTPS

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

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 创建本地受信任的证书。在生产环境中，应使用受信任机构颁发的正式证书。

值得注意的是：当部署到 Vercel 时，会自动配置 Next.js 应用的 HTTPS。

为下游代理配置超时

当在下游代理（例如 AWS ELB/ALB 负载均衡器）后面部署 Next.js 时，重要的是要将 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