Next.js CLI

Next.js CLI 允許您開發、建置、啟動您的應用程式等等。

基本用法

終端機

npx next [command] [options]

參考

以下選項可用：

選項	說明
`-h` 或 `--help`	顯示所有可用選項
`-v` 或 `--version`	輸出 Next.js 版本號碼

指令

以下指令可用：

指令	說明
`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。

`next dev` 選項

next dev 以開發模式啟動應用程式，包含熱模組更新 (HMR)、錯誤報告等功能。執行 next dev 時，可以使用以下選項：

選項	說明
`-h, --help`	顯示所有可用選項。
`[目錄]`	建置應用程式的目錄。如果未提供，則使用目前目錄。
`--turbo`	使用 Turbopack 啟動開發模式。
`-p` 或 `--port <連接埠>`	指定啟動應用程式的連接埠號碼。預設值：3000，環境變數：PORT
`-H` 或 `--hostname <主機名稱>`	指定啟動應用程式的主機名稱。適用於讓應用程式可供網路上的其他裝置使用。預設值：0.0.0.0
`--experimental-https`	使用 HTTPS 啟動伺服器並產生自我簽署的憑證。
`--experimental-https-key <路徑>`	HTTPS 金鑰檔案的路徑。
`--experimental-https-cert <路徑>`	HTTPS 憑證檔案的路徑。
`--experimental-https-ca <path>`	HTTPS 憑證授權單位檔案的路徑。
`--experimental-upload-trace <traceUrl>`	將部分除錯追蹤報告傳送到遠端 HTTP URL。

`next build` 選項

next build 會建立您應用程式的最佳化生產版本。輸出會顯示每個路由的相關資訊。例如：

終端機

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

大小：用戶端導覽到頁面時下載的資源大小。每個路由的大小僅包含其相依性。
首次載入 JS：從伺服器訪問頁面時下載的資源大小。所有頁面共用的 JS 量會顯示為單獨的指標。

這兩個值都已使用 gzip 壓縮。首次載入會以綠色、黃色或紅色指示。高效能應用程式應以綠色為目標。

以下選項適用於 next build 指令

選項	說明
`-h, --help`	顯示所有可用選項。
`[目錄]`	建置應用程式的目錄。如果未提供，則會使用目前的目錄。
`-d` 或 `--debug`	啟用更詳細的建置輸出。啟用此旗標後，將會顯示額外的建置輸出，例如重寫、重新導向和標頭。

`--profile`	為 React 啟用生產環境效能分析。
`--no-lint`	停用程式碼檢查。
`--no-mangling`	停用名稱修改。這可能會影響效能，並且僅應用於除錯目的。
`--experimental-app-only`	僅建置應用程式路由器路由。
`--experimental-build-mode [mode]`	使用實驗性建置模式。（選項：「compile」、「generate」，預設值：「default」）

`next start` 選項

next start 以生產模式啟動應用程式。應用程式應先使用 next build 編譯。

以下選項適用於 next start 指令

選項	說明
`-h` 或 `--help`	顯示所有可用選項。
`[目錄]`	啟動應用程式的目錄。如果未提供目錄，則會使用目前的目錄。
`-p` 或 `--port <連接埠>`	指定啟動應用程式的埠號。（預設值：3000，環境變數：PORT）
`-H` 或 `--hostname <hostname>`	指定啟動應用程式的主機名稱（預設值：0.0.0.0）。
`--keepAliveTimeout <keepAliveTimeout>`	指定在關閉非使用中連線之前要等待的最長時間（以毫秒為單位）。

`next info` 選項

`next info` 會印出與目前系統相關的詳細資訊，這些資訊可用於在開啟 GitHub 問題時回報 Next.js 錯誤。這些資訊包含作業系統平台／架構／版本、二進制檔案（Node.js、npm、Yarn、pnpm）、套件版本（`next`、`react`、`react-dom`）等等。

輸出應該如下所示

終端機

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` 指令提供以下選項

選項	說明
`-h` 或 `--help`	顯示所有可用選項
`--verbose（詳細）`	收集用於除錯的額外資訊。

`next lint` 選項

`next lint` 會對 `pages/`、`app/`、`components/`、`lib/` 和 `src/` 目錄中的所有檔案執行 ESLint。如果您的應用程式中尚未設定 ESLint，它還會提供引導式設定來安裝任何必要的相依套件。

`next lint` 指令提供以下選項

選項	說明
`[目錄]`	要對應用程式執行程式碼檢查的基底目錄。如果未提供，將使用目前目錄。
`-d, --dir, <目錄...>`	包含要執行 ESLint 的目錄。
`--file, <檔案...>`	包含要執行 ESLint 的檔案。
`--ext, [副檔名...]`	指定 JavaScript 檔案副檔名。（預設值：[".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx"])
`-c, --config, <設定檔>`	使用此設定檔，覆寫所有其他設定選項。
`--resolve-plugins-relative-to, <rprt>`	指定應從中解析外掛程式的目錄。
`--strict（嚴格）`	使用 Next.js 嚴格設定建立 `eslintrc.json` 檔案。
`--rulesdir, <規則目錄...>`	使用來自此目錄的額外規則。
`--fix（修復）`	自動修復程式碼檢查問題。
`--fix-type <修復類型>`	指定要套用的修復類型（例如：problem、suggestion、layout）。
`--ignore-path <路徑>`	指定要忽略的檔案。
`--no-ignore <路徑>`	停用 `--ignore-path` 選項。
`--quiet（安靜）`	僅回報錯誤。
`--max-warnings [最大警告數]`	指定在觸發非零退出代碼之前的警告數。（預設值：-1）
`-o, --output-file, <輸出檔案>`	指定要將報告寫入的檔案。
`-f, --format, <格式>`	使用特定的輸出格式。
`--no-inline-config`	防止註釋變更設定或規則。
`--report-unused-disable-directives-severity <級別>`	指定未使用的 eslint-disable 指令的嚴重性等級。（選項："error"、"off"、"warn"）
`--no-cache`	停用快取。
`--cache-location, <cacheLocation>`	指定快取位置。
`--cache-strategy, [cacheStrategy]`	指定用於偵測快取中已更改檔案的策略。（預設值："metadata"）
`--error-on-unmatched-pattern`	當任何檔案模式不符時回報錯誤。
`-h, --help`	顯示此訊息。

`next telemetry` 選項

Next.js 會收集關於一般使用情況的完全匿名遙測數據。參與此匿名程式是可選的，如果您不想分享資訊，您可以選擇退出。

以下選項適用於 next telemetry 指令

選項	說明
`-h, --help`	顯示所有可用選項。
`--enable`	啟用 Next.js 的遙測數據收集。
`--disable`	停用 Next.js 的遙測數據收集。

深入瞭解遙測。

範例

更改預設埠

預設情況下，Next.js 在開發期間和使用 next start 時使用 https://127.0.0.1:3000。可以使用 -p 選項更改預設埠，如下所示

終端機

next dev -p 4000

或使用 PORT 環境變數

終端機

PORT=4000 next dev

注意事項：由於 HTTP 伺服器的啟動發生在任何其他程式碼初始化之前，因此無法在 .env 中設定 PORT。

在開發期間使用 HTTPS

對於某些使用情境，例如 Webhook 或驗證，您可以使用 HTTPS 在 localhost 上建立安全環境。Next.js 可以使用 --experimental-https 旗標，透過 next dev 產生自簽憑證

終端機

next dev --experimental-https

使用產生的憑證，Next.js 開發伺服器將位於 https://127.0.0.1:3000。除非使用 -p、--port 或 PORT 指定埠，否則將使用預設埠 3000。

您也可以使用 --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 時，Next.js 應用程式的 HTTPS 會自動設定。

設定下游代理伺服器的逾時

當將 Next.js 部署在下游代理伺服器（例如 AWS ELB/ALB 等負載平衡器）之後時，務必使用 *大於* 下游代理伺服器逾時的保持連線逾時來設定 Next 底層的 HTTP 伺服器。否則，一旦達到特定 TCP 連線的保持連線逾時，Node.js 會立即終止該連線，而不會通知下游代理伺服器。這會導致代理伺服器在嘗試重複使用 Node.js 已終止的連線時發生錯誤。

要設定正式環境 Next.js 伺服器的逾時值，請將 --keepAliveTimeout（以毫秒為單位）傳遞給 next start，如下所示

終端機

next start --keepAliveTimeout 70000

傳遞 Node.js 參數

您可以將任何 node 參數傳遞給 next 指令。例如

終端機

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