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.

你可以傳遞任何 node 參數給 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（測試版）是我們的新組合器，正在 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 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' 搭配使用。

保持連線逾時

在下游代理伺服器 (例如 AWS ELB/ALB 等負載平衡器) 後方部署 Next.js 時，務必使用保持連線逾時來設定 Next 的底層 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 會執行所有檔案的 ESLint，這些檔案位於 pages/、app/、components/、lib/ 和 src/ 目錄中。如果您的應用程式尚未設定 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.

如果您有其他目錄想要進行 linting，您可以使用 --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.dev.org.tw/telemetry

進一步了解遙測。