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

next CLI 指令

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

基本用法：

Terminal
npm run 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]指定建構應用程式的目錄。若未提供，則使用當前目錄。
--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 為您的應用程式建立優化的生產環境建構版本。輸出會顯示每個路由的資訊，例如：

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停用 名稱改編 (Name 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>指定啟動應用程式的埠號。(預設值：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
作業系統：
  平台：darwin
  架構：arm64
  版本：Darwin Kernel Version 23.6.0
  可用記憶體 (MB)：65536
  可用 CPU 核心：10
二進位檔：
  Node：20.12.0
  npm：10.5.0
  Yarn：1.22.19
  pnpm：9.6.0
相關套件：
  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 設定：
  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...>從此目錄(s) 使用額外的規則。
--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

您也可以透過 --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 建立本地信任的憑證。在正式環境中，請使用由受信任機構核發的正式憑證。

須知：當您部署至 Vercel 時，系統會為您的 Next.js 應用程式自動設定 HTTPS。

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

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

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

Terminal
next start --keepAliveTimeout 70000

傳遞 Node.js 參數

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

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

create-next-app

使用 create-next-app CLI 指令，透過單一命令建立 Next.js 應用程式。

架構

Next.js 的運作原理

On this page