Next.js 中文网

主题

next CLI ​

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

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

基本用法：

¥Basic usage:

bash
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 错误。
telemetry允许你启用或禁用 Next.js 的完全匿名遥测收集。
typegen无需运行完整构建即可生成路由、页面、布局和路由处理程序的 TypeScript 定义。
upgrade将你的 Next.js 应用升级到最新版本。
experimental-analyze使用 Turbopack 分析打包包输出。不生成构建产物。

需要了解：不使用命令运行 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（默认启用）。也可作为 --turbo 使用。
--webpack在开发过程中使用 Webpack 而不是默认的 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:

bash
Route (app)
┌ ○ /_not-found
└ ƒ /products/[id]

○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

next build 命令有以下选项：

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

选项描述
-h, --help显示所有可用选项。
[directory]用于构建应用的目录。如果未提供，则将使用当前目录。
--turbopack强制启用 Turbopack（默认启用）。也可作为 --turbo 使用。
--webpack使用 Webpack 构建。
-d 或 --debug启用更详细的构建输出。启用此标志后，将显示其他构建输出，例如重写、重定向和标头。
--profile启用生产 React 分析。
--no-lint禁用 linting。注意：Linting 功能将于 Next 16 年从 next build 中移除。如果你使用的是 Next 15.5+ 版本，并且使用的是 eslint 以外的 linter，则构建期间将不会进行 linter。
--no-mangling禁用 mangling。这可能会影响性能，并且只能用于调试目的。
--experimental-app-only仅构建 App Router 路由。
--experimental-build-mode [mode]使用实验性构建模式。（选项："compile"、"generate"，默认值："default"）
--debug-prerender在开发模式下调试预渲染错误。
--debug-build-paths=<patterns>仅构建用于调试的特定路由。

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:

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

next typegen 选项 ​

¥next typegen options

next typegen 无需执行完整构建即可为应用的路由生成 TypeScript 定义。这对于 IDE 自动补齐和 CI 路由使用情况的类型检查非常有用。

¥next typegen generates TypeScript definitions for your application's routes without performing a full build. This is useful for IDE autocomplete and CI type-checking of route usage.

以前，路由类型仅在 next dev 或 next build 期间生成，这意味着直接运行 tsc --noEmit 不会验证你的路由类型。现在你可以独立生成类型并在外部验证它们：

¥Previously, route types were only generated during next dev or next build, which meant running tsc --noEmit directly wouldn't validate your route types. Now you can generate types independently and validate them externally:

bash
# Generate route types first, then validate with TypeScript
next typegen && tsc --noEmit

# Or in CI workflows for type checking without building
next typegen && npm run type-check

next typegen 命令有以下选项：

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

选项描述
-h, --help显示所有可用选项。
[directory]用于生成类型的目录。如果未提供，则将使用当前目录。

输出文件写入 <distDir>/types（通常为：.next/dev/types 或 .next/types，参见 isolatedDevBuild）：

¥Output files are written to <distDir>/types (typically: .next/dev/types or .next/types, see isolatedDevBuild):

bash
next typegen
# or for a specific app
next typegen ./apps/web

此外，next typegen 会生成一个 next-env.d.ts 文件。我们建议将 next-env.d.ts 添加到你的 .gitignore 文件中。

¥Additionally, next typegen generates a next-env.d.ts file. We recommend adding next-env.d.ts to your .gitignore file.

next-env.d.ts 文件包含在你的 tsconfig.json 文件中，以便 Next.js 类型可供你的项目使用。

¥The next-env.d.ts file is included into your tsconfig.json file, to make Next.js types available to your project.

为了确保 next-env.d.ts 存在，请在运行 next typegen 之前进行类型检查。命令 next dev 和 next build 也会生成 next-env.d.ts 文件，但通常不希望仅仅为了进行类型检查而运行这些命令，例如在 CI/CD 环境中。

¥To ensure next-env.d.ts is present before type-checking run next typegen. The commands next dev and next build also generate the next-env.d.ts file, but it is often undesirable to run these just to type-check, for example in CI/CD environments.

需要了解：next typegen 使用生产构建阶段加载你的 Next.js 配置（next.config.js、next.config.mjs 或 next.config.ts）。确保所有必需的环境变量和依赖都可用，以便配置能够正确加载。

¥Good to know: next typegen loads your Next.js config (next.config.js, next.config.mjs, or next.config.ts) using the production build phase. Ensure any required environment variables and dependencies are available so the config can load correctly.

next upgrade 选项 ​

¥next upgrade options

next upgrade 会将你的 Next.js 应用升级到最新版本。

¥next upgrade upgrades your Next.js application to the latest version.

next upgrade 命令有以下选项：

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

选项描述
-h, --help显示所有可用选项。
[directory]包含要升级的 Next.js 应用的目录。如果未提供，则将使用当前目录。
--revision <revision>指定要升级到的 Next.js 版本或标签（例如，latest、canary、15.0.0）。默认为你当前安装的发布渠道。
--verbose升级过程中显示详细输出。

next experimental-analyze 选项 ​

¥next experimental-analyze options

next experimental-analyze 使用 Turbopack 分析应用的打包输出。此命令可帮助你了解包的大小和组成，包括 JavaScript、CSS 和其他资源。此命令不会生成应用构建。

¥next experimental-analyze analyzes your application's bundle output using Turbopack. This command helps you understand the size and composition of your bundles, including JavaScript, CSS, and other assets. This command doesn't produce an application build.

bash
npx next experimental-analyze

默认情况下，该命令会在分析完成后启动一个本地服务器，以便你在浏览器中查看你的包组成。分析器允许你：

¥By default, the command starts a local server after analysis completes, allowing you to explore your bundle composition in the browser. The analyzer lets you:

  • 按路由筛选 bundle，并在客户端和服务器视图之间切换。

    ¥Filter bundles by route and switch between client and server views

  • 查看完整的导入链，了解模块被包含的原因

    ¥View the full import chain showing why a module is included

  • 追踪跨服务器端到客户端组件边界的导入以及动态导入

    ¥Trace imports across server-to-client component boundaries and dynamic imports

请参阅 软件包打包 以了解优化策略。

¥See Package Bundling for optimization strategies.

要在不启动服务器的情况下将分析输出写入磁盘，请使用 --output 标志。输出结果写入 .next/diagnostics/analyze，其中包含可复制到其他位置或与他人共享的静态文件：

¥To write the analysis output to disk without starting the server, use the --output flag. The output is written to .next/diagnostics/analyze and contains static files that can be copied elsewhere or shared with others:

bash
# Write output to .next/diagnostics/analyze
npx next experimental-analyze --output

# Copy the output for comparison with a future analysis
cp -r .next/diagnostics/analyze ./analyze-before-refactor

next experimental-analyze 命令有以下选项：

¥The following options are available for the next experimental-analyze command:

选项描述
-h, --help显示所有可用选项。
[directory]用于分析应用的目录。如果未提供，则将使用当前目录。
--no-mangling禁用 mangling。这可能会影响性能，并且只能用于调试目的。
--profile启用生产 React 分析。这可能会影响性能。
-o, --output无需启动服务器即可将分析文件写入磁盘。输出写入 .next/diagnostics/analyze。
--port <port>指定用于运行分析器的端口号。（默认值：4000，环境变量：端口)

示例 ​

¥Examples

调试预渲染错误 ​

¥Debugging prerender errors

如果在 next build 期间遇到预渲染错误，可以传递 --debug-prerender 标志以获取更详细的输出：

¥If you encounter prerendering errors during next build, you can pass the --debug-prerender flag to get more detailed output:

bash
next build --debug-prerender

这启用了几个实验性选项，使调试更容易：

¥This enables several experimental options to make debugging easier:

  • 禁用服务器代码压缩：

    ¥Disables server code minification:

    • experimental.serverMinification = false

    • experimental.turbopackMinify = false

  • 为服务器包生成源映射：

    ¥Generates source maps for server bundles:

    • experimental.serverSourceMaps = true

  • 在用于预渲染的子进程中启用源映射：

    ¥Enables source map consumption in child processes used for prerendering:

    • enablePrerenderSourceMaps = true

  • 即使在第一次预渲染错误后仍继续构建，因此你可以一次看到所有问题：

    ¥Continues building even after the first prerender error, so you can see all issues at once:

    • experimental.prerenderEarlyExit = false

这有助于在构建输出中显示更易读的堆栈跟踪和代码帧。

¥This helps surface more readable stack traces and code frames in the build output.

警告：--debug-prerender 仅用于开发调试。请勿将使用 --debug-prerender 生成的构建部署到生产环境，因为这可能会影响性能。

¥Warning: --debug-prerender is for debugging in development only. Do not deploy builds generated with --debug-prerender to production, as it may impact performance.

构建特定路由 ​

¥Building specific routes

你可以使用 --debug-build-paths 选项在应用和页面路由中构建特定的路由。这对于在处理大型应用时加快调试速度非常有用。--debug-build-paths 选项接受逗号分隔的文件路径，并支持 glob 模式：

¥You can build only specific routes in the App and Pages Routers using the --debug-build-paths option. This is useful for faster debugging when working with large applications. The --debug-build-paths option accepts comma-separated file paths and supports glob patterns:

bash
# Build a specific route
next build --debug-build-paths="app/page.tsx"

# Build more than one route
next build --debug-build-paths="app/page.tsx,pages/index.tsx"

# Use glob patterns
next build --debug-build-paths="app/**/page.tsx"
next build --debug-build-paths="pages/*.tsx"

更改默认端口 ​

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

bash
next dev -p 4000

或者使用 PORT 环境变量：

¥Or using the PORT environment variable:

bash
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:

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

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

为下游代理配置超时 ​

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

bash
next start --keepAliveTimeout 70000

传递 Node.js 参数 ​

¥Passing Node.js arguments

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

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

bash
NODE_OPTIONS='--throw-deprecation' next
NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' next
版本更改
v16.1.0添加 next experimental-analyze 命令
v16.0.0next build 中已移除 JS 包大小指标。
v15.5.0添加 next typegen 命令
v15.4.0为 next build 添加 --debug-prerender 选项，以帮助调试预渲染错误。