Next.js CLI

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

要获取可用 CLI 命令的列表，请在您的项目目录中运行以下命令

终端

next -h

输出应如下所示

终端

Usage next [options] [command]
 
The Next.js CLI allows you to develop, build, start your application, and more.
 
Options:
  -v, --version                Outputs the Next.js version.
  -h, --help                   Displays this message.
 
Commands:
  build [directory] [options]  Creates an optimized production build of your application.
                               The output displays information about each route.
  dev [directory] [options]    Starts Next.js in development mode with hot-code reloading,
                               error reporting, and more.
  info [options]               Prints relevant details about the current system which can be
                               used to report Next.js bugs.
  lint [directory] [options]   Runs ESLint for all files in the `/src`, `/app`, `/pages`,
                               `/components`, and `/lib` directories. It also provides a
                               guided setup to install any required dependencies if ESLint
                               is not already configured in your application.
  start [directory] [options]  Starts Next.js in production mode. The application should be
                               compiled with `next build` first.
  telemetry [options]          Allows you to enable or disable Next.js' completely
                               anonymous telemetry collection.

您可以将任何节点参数传递给 next 命令

终端

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

注意：在没有命令的情况下运行 next 等同于运行 next dev

开发

next dev 以开发模式启动应用程序，具有热代码重载、错误报告等功能。

要获取 next dev 可用选项的列表，请在您的项目目录中运行以下命令

终端

next dev -h

输出应如下所示

终端

Usage: next dev [directory] [options]
 
Starts Next.js in development mode with hot-code reloading, error reporting, and more.
 
Arguments:
  [directory]                              A directory on which to build the application.
                                           If no directory is provided, the current
                                           directory will be used.
 
Options:
  --turbo                                  Starts development mode using Turbopack (beta).
  -p, --port <port>                        Specify a port number on which to start the
                                           application. (default: 3000, env: PORT)
  -H, --hostname <hostname>                Specify a hostname on which to start the
                                           application (default: 0.0.0.0).
  --experimental-https                     Starts the server with HTTPS and generates a
                                           self-signed certificate.
  --experimental-https-key, <path>         Path to a HTTPS key file.
  --experimental-https-cert, <path>        Path to a HTTPS certificate file.
  --experimental-https-ca, <path>          Path to a HTTPS certificate authority file.
  --experimental-upload-trace, <traceUrl>  Reports a subset of the debugging trace to a
                                           remote HTTP URL. Includes sensitive data.
  -h, --help                               Displays this message.

应用程序默认将在 https://127.0.0.1:3000 上启动。默认端口可以使用 -p 更改，如下所示

终端

next dev -p 4000

或者使用 PORT 环境变量

终端

PORT=4000 next dev

注意:

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

如果未通过 CLI 选项 --port 或 PORT 环境变量指定端口，Next.js 将自动尝试使用另一个端口，直到找到可用端口。

您还可以将主机名设置为与默认的 0.0.0.0 不同，这对于使应用程序可供网络上的其他设备使用很有用。默认主机名可以使用 -H 更改，如下所示

终端

next dev -H 192.168.1.2

Turbopack

Turbopack (beta)，我们新的打包器，正在 Next.js 中进行测试和稳定，有助于加快在应用程序上工作时的本地迭代。

要在开发模式下使用 Turbopack，请添加 --turbo 选项

终端

next dev --turbo

本地开发的 HTTPS

对于某些用例，例如 webhook 或身份验证，可能需要使用 HTTPS 在 localhost 上拥有安全的环境。Next.js 可以使用 next dev 生成自签名证书，如下所示

终端

next dev --experimental-https

您也可以使用 --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 应用程序。

构建

next build 创建应用程序的优化生产版本。输出显示有关每个路由的信息

终端

Route (app)                               Size     First Load JS
┌ ○ /                                     5.3 kB         89.5 kB
├ ○ /_not-found                           885 B          85.1 kB
└ ○ /about                                137 B          84.4 kB
+ First Load JS shared by all             84.2 kB
  ├ chunks/184-d3bb186aac44da98.js        28.9 kB
  ├ chunks/30b509c0-f3503c24f98f3936.js   53.4 kB
  └ other shared chunks (total)
 
 
○  (Static)  prerendered as static content

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

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

要获取使用 next build 可用选项的列表，请在项目目录中运行以下命令

终端

next build -h

输出应如下所示

终端

Usage: next build [directory] [options]
 
Creates an optimized production build of your application. The output displays information
about each route.
 
Arguments:
  [directory]                       A directory on which to build the application. If no
                                    provided, the current directory will be
                                    used.
 
Options:
  -d, --debug                       Enables a more verbose build output.
  --profile                         Enables production profiling for React.
  --no-lint                         Disables linting.
  --no-mangling                     Disables mangling.
  --experimental-app-only           Builds only App Router routes.
  --experimental-build-mode [mode]  Uses an experimental build mode. (choices: "compile"
                                    "generate", default: "default")
  -h, --help                        Displays this message.

分析

您可以使用 next build 中的 --profile 标志为 React 启用生产分析。

终端

next build --profile

之后，您可以像在开发中一样使用分析器。

调试

您可以使用 next build 中的 --debug 标志启用更详细的构建输出。

终端

next build --debug

启用此标志后，将显示重写、重定向和标头等其他构建输出。

代码风格检查

您可以像这样禁用构建的代码风格检查

终端

next build --no-lint

混淆

您可以像这样禁用构建的混淆

终端

next build --no-mangling

注意: 这可能会影响性能，仅应用于调试目的。

生产环境

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

要获取 next start 可用选项的列表，请在项目目录中运行以下命令

终端

next start -h

输出应如下所示

终端

Usage: next start [directory] [options]
 
Starts Next.js in production mode. The application should be compiled with `next build`
first.
 
Arguments:
  [directory]                           A directory on which to start the application.
                                        If not directory is provided, the current
                                        directory will be used.
 
Options:
  -p, --port <port>                     Specify a port number on which to start the
                                        application. (default: 3000, env: PORT)
  -H, --hostname <hostname>             Specify a hostname on which to start the
                                        application (default: 0.0.0.0).
  --keepAliveTimeout <keepAliveTimeout> Specify the maximum amount of milliseconds to wait
                                        before closing the inactive connections.
  -h, --help                            Displays this message.

应用程序默认将在 https://127.0.0.1:3000 上启动。默认端口可以使用 -p 更改，如下所示

终端

next start -p 4000

或者使用 PORT 环境变量

终端

PORT=4000 next start

注意:

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

next start 不能与 output: 'standalone' 或 output: 'export' 一起使用。

保持活动超时

在将 Next.js 部署到下游代理（例如 AWS ELB/ALB 等负载均衡器）之后，使用保持活动超时配置 Next.js 底层的 HTTP 服务器，该超时时间应大于下游代理的超时时间。否则，一旦给定 TCP 连接达到保持活动超时，Node.js 将立即终止该连接，而不会通知下游代理。这会导致代理错误，无论何时它尝试重用 Node.js 已经终止的连接。

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

终端

next start --keepAliveTimeout 70000

信息

next info 打印与当前系统相关的详细信息，可用于报告 Next.js 错误。这些信息包括操作系统平台/架构/版本、二进制文件（Node.js、npm、Yarn、pnpm）和 npm 包版本（next、react、react-dom）。

要获取 next info 可用选项的列表，请在项目目录中运行以下命令

终端

next info -h

输出应如下所示

终端

Usage: next info [options]
 
Prints relevant details about the current system which can be used to report Next.js bugs.
 
Options:
  --verbose   Collections additional information for debugging.
  -h, --help  Displays this message.

运行 next info 将提供类似以下示例的信息

终端

 
Operating System:
  Platform: linux
  Arch: x64
  Version: #22-Ubuntu SMP Fri Nov 5 13:21:36 UTC 2021
  Available memory (MB): 31795
  Available CPU cores: 16
Binaries:
  Node: 16.13.0
  npm: 8.1.0
  Yarn: 1.22.17
  pnpm: 6.24.2
Relevant Packages:
  next: 14.1.1-canary.61 // Latest available version is detected (14.1.1-canary.61).
  react: 18.2.0
  react-dom: 18.2.0
Next.js Config:
  output: N/A

然后将这些信息粘贴到 GitHub Issues 中。

您还可以运行 next info --verbose，它将打印有关系统和与 next 相关的软件包安装的更多信息。

Lint

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

要获取 next lint 可用选项的列表，请在项目目录中运行以下命令

终端

next lint -h

输出应如下所示

终端

Usage: next lint [directory] [options]
 
Runs ESLint for all files in the `/src`, `/app`, `/pages`, `/components`, and `/lib`
directories. It also provides a guided setup to install any required dependencies if ESLint
is not already configured in your application.
 
Arguments:
  [directory]                            A base directory on which to lint the application.
                                         If no directory is provided, the current
                                         directory will be used.
 
Options:
  -d, --dir, <dirs...>                   Include directory, or directories, to run ESLint.
  --file, <files...>                     Include file, or files, to run ESLint.
  --ext, [exts...]                       Specify JavaScript file extensions. (default:
                                         [".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".ts
x"])
  -c, --config, <config>                 Uses this configuration file, overriding all other
                                         configuration options.
  --resolve-plugins-relative-to, <rprt>  Specify a directory where plugins should be
                                         resolved from.
  --strict                               Creates a `.eslintrc.json` file using the Next.js
                                         strict configuration.
  --rulesdir, <rulesdir...>              Uses additional rules from this directory(s).
  --fix                                  Automatically fix linting issues.
  --fix-type <fixType>                   Specify the types of fixes to apply (e.g., problem,
                                         suggestion, layout).
  --ignore-path <path>                   Specify a file to ignore.
  --no-ignore <path>                     Disables the `--ignore-path` option.
  --quiet                                Reports errors only.
  --max-warnings [maxWarnings]           Specify the number of warnings before triggering a
                                         non-zero exit code. (default: -1)
  -o, --output-file, <outputFile>        Specify a file to write report to.
  -f, --format, <format>                 Uses a specifc output format.
  --no-inline-config                     Prevents comments from changing config or rules.
  --report-unused-disable-directives     Adds reprted errors for unused eslint-disable
                                         directives.
  --no-cache                             Disables caching.
  --cache-location, <cacheLocation>      Specify a location for cache.
  --cache-strategy, [cacheStrategy]      Specify a strategy to use for detecting changed
                                         files in the cache. (default: "metadata")
  --error-on-unmatched-pattern           Reports errors when any file patterns are
                                         unmatched.
  -h, --help                             Displays this message.

如果您还有其他要 lint 的目录，可以使用 --dir 标志指定它们

终端

next lint --dir utils

有关其他选项的更多信息，请查看我们的 ESLint 配置文档。

遥测

Next.js 收集关于一般使用情况的完全匿名遥测数据。参与此匿名计划是可选的，如果您不想分享任何信息，可以选择退出。

要获取使用 next telemetry 可用选项的列表，请在您的项目目录中运行以下命令

终端

next telemetry -h

输出应如下所示

终端

Usage: next telemetry [options]
 
Allows you to enable or disable Next.js' completely anonymous telemetry collection.
 
Options:
  --enable    Eanbles Next.js' telemetry collection.
  --disable   Disables Next.js' telemetry collection.
  -h, --help  Displays this message.
 
Learn more: https://nextjs.net.cn/telemetry

了解更多关于遥测。