Skip to main content

Next.js CLI

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

¥The Next.js CLI allows you to develop, build, start your application, and more.

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

¥To get a list of the available CLI commands, run the following command inside your project directory:

next -h

输出应如下所示：

¥The output should look like this:

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 命令：

¥You can pass any node arguments to next commands:

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

很高兴知道：不使用命令运行 next 与运行 next dev 相同

¥Good to know: Running next without a command is the same as running next dev

开发​

¥Development

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

¥next dev starts the application in development mode with hot-code reloading, error reporting, and more.

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

¥To get a list of the available options with next dev, run the following command inside your project directory:

next dev -h

输出应如下所示：

¥The output should look like this:

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.

默认情况下，应用将在 http://localhost:3000 启动。可以使用 -p 更改默认端口，如下所示：

¥The application will start at http://localhost:3000 by default. The default port can be changed with -p, like so:

next dev -p 4000

或者使用 PORT 环境变量：

¥Or using the PORT environment variable:

PORT=4000 next dev

很高兴知道：

¥Good to know:

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

    ¥PORT cannot be set in .env as booting up the HTTP server happens before any other code is initialized.

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

    ¥Next.js will automatically retry with another port until a port is available if a port is not specified with the CLI option --port or the PORT environment variable.

你还可以将主机名设置为不同于默认值 0.0.0.0，这对于使应用可用于网络上的其他设备非常有用。可以使用 -H 更改默认主机名，如下所示：

¥You can also set the hostname to be different from the default of 0.0.0.0, this can be useful for making the application available for other devices on the network. The default hostname can be changed with -H, like so:

next dev -H 192.168.1.2

Turbopack​

Turbopack（测试版）是我们的新打包器，正在 Next.js 中进行测试和稳定，有助于在处理应用时加快本地迭代速度。

¥Turbopack (beta), our new bundler, which is being tested and stabilized in Next.js, helps speed up local iterations while working on your application.

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

¥To use Turbopack in development mode, add the --turbo option:

next dev --turbo

用于本地开发的 HTTPS​

¥HTTPS for Local Development

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

¥For certain use cases like webhooks or authentication, it may be required to use HTTPS to have a secure environment on localhost. Next.js can generate a self-signed certificate with next dev as follows:

next dev --experimental-https

你还可以使用 --experimental-https-key 和 --experimental-https-cert 提供自定义证书和密钥。或者，你也可以提供带有 --experimental-https-ca 的自定义 CA 证书。

¥You can also provide a custom certificate and key with --experimental-https-key and --experimental-https-cert. Optionally, you can provide a custom CA certificate with --experimental-https-ca as well.

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 dev --experimental-https is only intended for development and creates a locally-trusted certificate with mkcert. In production, use properly issued certificates from trusted authorities. When deploying to Vercel, HTTPS is automatically configured for your Next.js application.

构建​

¥Build

next build 为你的应用创建优化的生产版本。输出显示有关每条路由的信息：

¥next build creates an optimized production build of your application. The output displays information about each route:

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

  • 尺寸：导航到客户端页面时下载的资源数量。每个路由的大小仅包括其依赖。

    ¥Size: The number of assets downloaded when navigating to the page client-side. The size for each route only includes its dependencies.

  • 首先加载 JS：从服务器访问页面时下载的资源数量。所有人共享的 JS 数量显示为单独的指标。

    ¥First Load JS: The number of assets downloaded when visiting the page from the server. The amount of JS shared by all is shown as a separate metric.

这两个值都是 使用 gzip 压缩。第一个负载用绿色、黄色或红色表示。致力于实现高性能应用的绿色化。

¥Both of these values are compressed with gzip. The first load is indicated by green, yellow, or red. Aim for green for performant applications.

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

¥To get a list of the available options with next build, run the following command inside your project directory:

next build -h

输出应如下所示：

¥The output should look like this:

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.

调试​

¥Debug

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

¥You can enable more verbose build output with the --debug flag in next build.

next build --debug

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

¥With this flag enabled additional build output like rewrites, redirects, and headers will be shown.

代码检查​

¥Linting

你可以像这样禁用构建的 linting：

¥You can disable linting for builds like so:

next build --no-lint

芒林​

¥Mangling

你可以像这样禁用 mangling 构建：

¥You can disable mangling for builds like so:

next build --no-mangling

很高兴知道：这可能会影响性能，并且只能用于调试目的。

¥Good to know: This may affect performance and should only be used for debugging purposes.

分析​

¥Profiling

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

¥You can enable production profiling for React with the --profile flag in next build.

next build --profile

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

¥After that, you can use the profiler in the same way as you would in development.

生产​

¥Production

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

¥next start starts the application in production mode. The application should be compiled with next build first.

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

¥To get a list of the available options with next start, run the follow command inside your project directory:

next start -h

输出应如下所示：

¥The output should look like this:

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.

默认情况下，应用将在 http://localhost:3000 启动。可以使用 -p 更改默认端口，如下所示：

¥The application will start at http://localhost:3000 by default. The default port can be changed with -p, like so:

next start -p 4000

或者使用 PORT 环境变量：

¥Or using the PORT environment variable:

PORT=4000 next start

很高兴知道：

¥Good to know:

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

    ¥PORT cannot be set in .env as booting up the HTTP server happens before any other code is initialized.

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

    ¥next start cannot be used with output: 'standalone' or output: 'export'.

保持活动超时​

¥Keep Alive Timeout

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

¥When deploying Next.js behind a downstream proxy (e.g. a load-balancer like AWS ELB/ALB) it's important to configure Next's underlying HTTP server with keep-alive timeouts that are larger than the downstream proxy's timeouts. Otherwise, once a keep-alive timeout is reached for a given TCP connection, Node.js will immediately terminate that connection without notifying the downstream proxy. This results in a proxy error whenever it attempts to reuse a connection that Node.js has already terminated.

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

¥To configure the timeout values for the production Next.js server, pass --keepAliveTimeout (in milliseconds) to next start, like so:

next start --keepAliveTimeout 70000

信息​

¥Info

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

¥next info prints relevant details about the current system which can be used to report Next.js bugs. This information includes Operating System platform/arch/version, Binaries (Node.js, npm, Yarn, pnpm) and npm package versions (next, react, react-dom).

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

¥To get a list of the available options with next info, run the following command inside your project directory:

next info -h

输出应如下所示：

¥The output should look like this:

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 将为你提供如下示例所示的信息：

¥Running next info will give you information like this example:


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 中。

¥This information should then be pasted into GitHub Issues.

你还可以运行 next info --verbose，它将打印有关系统以及与 next 相关的软件包安装的附加信息。

¥You can also run next info --verbose which will print additional information about the system and the installation of packages related to next.

代码检查​

¥Lint

next lint 对 pages/、app/、components/、lib/ 和 src/ 目录中的所有文件运行 ESLint。如果你的应用中尚未配置 ESLint，它还提供指导安装来安装任何所需的依赖。

¥next lint runs ESLint for all files in the pages/, app/, components/, lib/, and src/ directories. It also provides a guided setup to install any required dependencies if ESLint is not already configured in your application.

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

¥To get a list of the available options with next lint, run the following command inside your project directory:

next lint -h

输出应如下所示：

¥The output should look like this:

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", ".tsx"])
  -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-severity <level> Specify severity level for unused eslint-disable
                                                      directives. (choices: "error", "off", "warn")
  --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.

如果你想要检查其他目录，你可以使用 --dir 标志指定它们：

¥If you have other directories that you would like to lint, you can specify them using the --dir flag:

next lint --dir utils

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

¥For more information on the other options, check out our ESLint configuration documentation.

遥测​

¥Telemetry

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

¥Next.js collects completely anonymous telemetry data about general usage. Participation in this anonymous program is optional, and you may opt-out if you'd not like to share any information.

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

¥To get a list of the available options with next telemetry, run the following command in your project directory:

next telemetry -h

输出应如下所示：

¥The output should look like this:

Usage: next telemetry [options]

Allows you to enable or disable Next.js' completely anonymous telemetry collection.

Options:
  --enable    Enables Next.js' telemetry collection.
  --disable   Disables Next.js' telemetry collection.
  -h, --help  Displays this message.

Learn more: https://next.nodejs.cn/telemetry

了解有关 遥测 的更多信息。

¥Learn more about Telemetry.