logoNext.js 繁體中文
文件部落格學習
介紹/API 參考文檔/CLI/next CLI

next CLI

Next.js CLI 允許您開發、構建、啟動應用程式以及執行更多操作。

基本用法：

Terminal
npx next [command] [options]

參考資料

以下選項可供使用：

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

指令

以下指令可供使用：

指令描述
dev以開發模式啟動 Next.js，包含熱模組替換 (HMR)、錯誤報告等功能。
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>指定應用程式啟動的端口號。預設值：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 為您的應用程式建立優化的生產版本。輸出會顯示每個路由的資訊，例如：

Terminal
Route (app)                              Size     First Load JS
┌ ○ /_not-found                          0 B               0 kB
└ ƒ /products/[id]                       0 B               0 kB

○  (Static)   預渲染為靜態內容
ƒ  (Dynamic)  按需伺服器渲染
  • Size：在客戶端導航至頁面時下載的資源大小。每個路由的大小僅包含其依賴項。
  • First Load JS：從伺服器訪問頁面時下載的資源大小。所有路由共享的 JS 大小會單獨顯示為一個指標。

這些值均經過 gzip 壓縮。首次載入的效能以綠色、黃色或紅色標示。建議保持綠色以確保應用程式效能。

next build 指令的可用選項如下：

選項描述
-h, --help顯示所有可用選項。
[directory]指定構建應用程式的目錄。若未提供，則使用當前目錄。
-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顯示所有可用選項。
[directory]指定啟動應用程式的目錄。若未提供，則使用當前目錄。
-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）等。

輸出應類似以下內容：

Terminal
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 // 檢測到最新可用版本 (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]指定執行代碼檢查的基礎目錄。若未提供，則使用當前目錄。
-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 嚴格配置創建 .eslintrc.json 文件。
--rulesdir, <rulesdir...>從此目錄（可多個）使用額外的規則。
--fix自動修復代碼檢查問題。
--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 遙測數據收集。

了解更多關於 遙測數據。

範例

變更預設連接埠

預設情況下，Next.js 在開發環境和使用 next start 時會使用 http://localhost:3000。您可以使用 -p 選項來變更預設連接埠，如下所示：

Terminal
next dev -p 4000

或是使用 PORT 環境變數：

Terminal
PORT=4000 next dev

須知：PORT 無法在 .env 中設定，因為 HTTP 伺服器的啟動會在所有其他程式碼初始化之前完成。

在開發環境中使用 HTTPS

針對某些使用情境，例如網路掛鉤 (webhooks) 或身份驗證，您可以使用 HTTPS 在 localhost 上建立安全的環境。Next.js 可以透過 next dev 搭配 --experimental-https 標誌來產生自簽憑證：

Terminal
next dev --experimental-https

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

您也可以透過 --experimental-https-key 和 --experimental-https-cert 提供自訂的金鑰和憑證。此外，您還可以選擇使用 --experimental-https-ca 提供自訂的 CA 憑證。

Terminal
next dev --experimental-https --experimental-https-key ./certificates/localhost-key.pem --experimental-https-cert ./certificates/localhost.pem

next dev --experimental-https 僅適用於開發環境，並會使用 mkcert 建立本地信任的憑證。在正式環境中，請使用由可信機構正式發行的憑證。

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

當將 Next.js 部署在下游代理伺服器 (例如 AWS ELB/ALB 這類負載平衡器) 後方時，務必將 Next.js 底層 HTTP 伺服器的 保持連線逾時時間 (keep-alive timeouts) 設定為 大於 下游代理伺服器的逾時時間。否則，一旦某個 TCP 連線達到保持連線逾時時間，Node.js 會立即終止該連線而不通知下游代理伺服器。這會導致代理伺服器嘗試重複使用已被 Node.js 終止的連線時，發生代理伺服器錯誤。

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

Terminal
next start --keepAliveTimeout 70000

傳遞 Node.js 參數

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

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

create-next-app CLI

使用 create-next-app CLI 指令，只需一行命令即可建立 Next.js 應用程式。

架構

Next.js 的運作原理

On this page