next 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`	顯示所有可用選項。
`[directory]`	要在其中建置應用程式的目錄。如果未提供，則使用當前目錄。
`--turbopack`	使用 Turbopack 啟動開發模式。
`-p` 或 `--port <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`	顯示所有可用選項。
`[directory]`	要在其中建置應用程式的目錄。如果未提供，則使用當前目錄。
`-d` 或 `--debug`	啟用更詳細的建置輸出。啟用此標記後，將顯示額外的建置輸出，例如 rewrites、redirects 和 headers。

`--profile`	啟用 React 的生產環境 profiling。
`--no-lint`	停用 linting。
`--no-mangling`	停用 mangling。這可能會影響效能，應僅用於偵錯目的。
`--experimental-app-only`	僅建置 App Router 路由。
`--experimental-build-mode [mode]`	使用實驗性建置模式。（選項："compile"、"generate"，預設值："default"）

`next start` 選項

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

以下選項適用於 next start 命令

選項	描述
`-h` 或 `--help`	顯示所有可用選項。
`[directory]`	要在其中啟動應用程式的目錄。如果未提供目錄，則使用當前目錄。
`-p` 或 `--port <port>`	指定要啟動應用程式的 port 號碼。（預設值：3000，環境變數：PORT）
`-H` 或 `--hostname <hostname>`	指定要啟動應用程式的主機名稱（預設值：0.0.0.0）。
`--keepAliveTimeout <keepAliveTimeout>`	指定關閉非活動連線之前要等待的最大毫秒數。

`next info` 選項

當開啟 GitHub issue 時，next info 會印出關於當前系統的相關詳細資訊，可用於報告 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 命令

選項	描述
`[directory]`	要在其上執行 linting 的基本目錄。如果未提供，則使用當前目錄。
`-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 strict 設定建立 `.eslintrc.json` 檔案。
`--rulesdir, <rulesdir...>`	使用來自此目錄的其他規則。
`--fix`	自動修復 linting 問題。
`--fix-type <fixType>`	指定要應用的修復類型（例如，problem、suggestion、layout）。
`--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.js 收集關於一般用法的完全匿名遙測資料。參與此匿名計畫是可選的，如果您不希望分享資訊，可以選擇退出。

以下選項適用於 next telemetry 命令

選項	描述
`-h, --help`	顯示所有可用選項。
`--enable`	啟用 Next.js 的遙測資料收集。
`--disable`	停用 Next.js 的遙測資料收集。

深入瞭解遙測。

範例

變更預設 port

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

終端機

next dev -p 4000

或使用 PORT 環境變數

終端機

PORT=4000 next dev

小提示：PORT 無法在 .env 中設定，因為 HTTP 伺服器的啟動發生在任何其他程式碼初始化之前。

在開發期間使用 HTTPS

對於某些用例，例如 webhook 或身份驗證，您可以使用 HTTPS 在 localhost 上擁有安全環境。Next.js 可以使用 --experimental-https 標記，透過 next dev 產生自我簽署憑證

終端機

next dev --experimental-https

使用產生的憑證，Next.js 開發伺服器將存在於 https://localhost:3000。除非使用 -p、--port 或 PORT 指定 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 時，HTTPS 會為您的 Next.js 應用程式自動設定。

設定下游代理的逾時

當在下游代理（例如 AWS ELB/ALB 之類的負載平衡器）後方部署 Next.js 時，務必使用比下游代理的逾時時間更長的 keep-alive 逾時時間設定 Next.js 的底層 HTTP 伺服器。否則，一旦給定 TCP 連線達到 keep-alive 逾時時間，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