Skip to main content

下一个 CLI

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

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

基本用法：

¥Basic usage:

npx next [command] [options]

参考​

¥Reference

可以使用以下选项：

¥The following options are available:

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

命令​

¥Commands

以下命令可用：

¥The following commands are available:

命令描述
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 的别名。

¥Good to know: Running next without a command is an alias for next dev.

next dev 选项​

¥next dev options

next dev 以开发模式启动应用，具有热模块重新加载 (HMR)、错误报告等功能。运行 next dev 时有以下选项：

¥next dev starts the application in development mode with Hot Module Reloading (HMR), error reporting, and more. The following options are available when running 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 options

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

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

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

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

    ¥Size: The size 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 size 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 命令有以下选项：

¥The following options are available for the next build command:

选项描述
-h, --help显示所有可用选项。
[directory]用于构建应用的目录。如果未提供，则将使用当前目录。
-d 或 --debug启用更详细的构建输出。启用此标志后，将显示其他构建输出，例如重写、重定向和标头。
--profile启用生产 React 分析。
--no-lint禁用 linting。
--no-mangling禁用 mangling。这可能会影响性能，并且只能用于调试目的。
--experimental-app-only仅构建 App Router 路由。
--experimental-build-mode [mode]使用实验性构建模式。（选项："compile"、"generate"，默认值："default"）

next start 选项​

¥next start options

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

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

next start 命令有以下选项：

¥The following options are available for the next start command:

选项描述
-h 或 --help显示所有可用选项。
[directory]用于启动应用的目录。如果未提供目录，则将使用当前目录。
-p 或 --port <port>指定启动应用的端口号。(默认值：3000，环境：PORT)
-H 或 --hostname <hostname>指定启动应用的主机名（默认值：0.0.0.0）。
--keepAliveTimeout <keepAliveTimeout>指定关闭非活动连接前等待的最大毫秒数。

next info 选项​

¥next info options

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

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

输出应如下所示：

¥The output should look like this:

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 命令有以下选项：

¥The following options are available for the next info command:

选项描述
-h 或 --help显示所有可用选项
--verbose收集其他信息以进行调试。

next lint 选项​

¥next lint options

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 命令有以下选项：

¥The following options are available for the next lint command:

选项描述
[directory]用于对应用进行 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自动修复 linting 问题。
--fix-type <fixType>指定要应用的修复类型（例如，问题、建议、布局）。
--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 telemetry options

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

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

next telemetry 命令有以下选项：

¥The following options are available for the next telemetry command:

选项描述
-h, --help显示所有可用选项。
--enable启用 Next.js 的遥测收集。
--disable禁用 Next.js 的遥测收集。

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

¥Learn more about Telemetry.

示例​

¥Examples

更改默认端口​

¥Changing the default port

默认情况下，Next.js 在开发过程中和 next start 中使用 http://localhost:3000。可以使用 -p 选项更改默认端口，如下所示：

¥By default, Next.js uses http://localhost:3000 during development and with next start. The default port can be changed with the -p option, like so:

next dev -p 4000

或者使用 PORT 环境变量：

¥Or using the PORT environment variable:

PORT=4000 next dev

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

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

在开发过程中使用 HTTPS​

¥Using HTTPS during development

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

¥For certain use cases like webhooks or authentication, you can use HTTPS to have a secure environment on localhost. Next.js can generate a self-signed certificate with next dev using the --experimental-https flag:

next dev --experimental-https

使用生成的证书，Next.js 开发服务器将存在于 https://localhost:3000。除非使用 -p、--port 或 PORT 指定端口，否则将使用默认端口 3000。

¥With the generated certificate, the Next.js development server will exist at https://localhost:3000. The default port 3000 is used unless a port is specified with -p, --port, or PORT.

你还可以使用 --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 创建本地受信任的证书。在生产中，使用由受信任的机构正确颁发的证书。

¥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.

很高兴知道：部署到 Vercel 时，Next.js 应用的 HTTPS 为 自动配置。

¥Good to know: When deploying to Vercel, HTTPS is automatically configured for your Next.js application.

为下游代理配置超时​

¥Configuring a timeout for downstream proxies

在下游代理（例如 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

传递 Node.js 参数​

¥Passing Node.js arguments

你可以将任何 节点参数 传递给 next 命令。例如：

¥You can pass any node arguments to next commands. For example:

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