next CLI

Next.js CLI 讓您可以開發、建置、啟動您的應用程式等等。

基本用法

終端機

npx next [command] [options]

參考

以下選項可用

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

指令

以下指令可用：

指令	說明
`dev`	以開發模式啟動 Next.js，包含熱模組重新載入 (Hot Module Reloading)、錯誤報告等功能。
`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 <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 會建立您應用程式的最佳化生產版本。輸出會顯示每個路由的相關資訊。例如：

終端機

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`	僅建置 App Router 路由。
`--experimental-build-mode [mode]`	使用實驗性建置模式。(選項："compile", "generate", 預設值："default")

`next start` 選項

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

以下選項適用於 next start 指令：

選項	說明
`-h` 或 `--help`	顯示所有可用選項。
`[目錄]`	啟動應用程式的目錄。如果未提供目錄，則會使用目前的目錄。
`-p` 或 `--port <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, <快取位置>`	指定快取位置。
`--cache-strategy, [快取策略]`	指定用於偵測快取中已變更檔案的策略。(預設值："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