next CLI

Next.js CLI 允許你開發、構建、啟動應用程式等。

基本用法

npx next [command] [options]

參考

以下選項可用

命令

以下命令可用

須知：不帶命令執行 next 等同於 next dev。

next dev 選項

next dev 以開發模式啟動應用程式，支援熱模組過載 (HMR)、錯誤報告等。執行 next dev 時，以下選項可用

next build 選項

next build 建立應用程式的最佳化生產構建。輸出顯示有關每個路由的資訊。例如

Route (app)
┌ ○ /_not-found
└ ƒ /products/[id]
 
○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

next build 命令的以下選項可用

next start 選項

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

next start 命令的以下選項可用

next info 選項

next info 列印有關當前系統的相關詳細資訊，可用於在提交 GitHub issue 時報告 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 命令的以下選項可用

next telemetry 選項

Next.js 收集有關一般使用情況的完全匿名遙測資料。參與此匿名程式是可選的，如果你不願意分享資訊，可以選擇退出。

next telemetry 命令的以下選項可用

瞭解更多關於 遙測。

next typegen 選項

next typegen 為你的應用程式路由生成 TypeScript 定義，而無需執行完整的構建。這對於 IDE 自動補全和路由使用情況的 CI 型別檢查很有用。

以前，路由型別只在 next dev 或 next build 期間生成，這意味著直接執行 tsc --noEmit 不會驗證你的路由型別。現在你可以獨立生成型別並在外部驗證它們。

# Generate route types first, then validate with TypeScript
next typegen && tsc --noEmit
 
# Or in CI workflows for type checking without building
next typegen && npm run type-check

next typegen 命令的以下選項可用

輸出檔案寫入 <distDir>/types（預設值：.next/types）

next typegen
# or for a specific app
next typegen ./apps/web

須知：next typegen 使用生產構建階段載入你的 Next.js 配置（next.config.js、next.config.mjs 或 next.config.ts）。請確保所有必需的環境變數和依賴項都可用，以便配置能夠正確載入。

示例

除錯預渲染錯誤

如果在 next build 期間遇到預渲染錯誤，可以傳遞 --debug-prerender 標誌以獲取更詳細的輸出

next build --debug-prerender

這會啟用幾個實驗性選項以簡化除錯

• 停用伺服器程式碼壓縮
  • experimental.serverMinification = false
  • experimental.turbopackMinify = false
• 為伺服器捆綁包生成源對映
  • experimental.serverSourceMaps = true
• 在用於預渲染的子程序中啟用源對映消耗
  • enablePrerenderSourceMaps = true
• 即使在第一次預渲染錯誤之後也繼續構建，這樣你就可以一次性看到所有問題
  • experimental.prerenderEarlyExit = false

這有助於在構建輸出中顯示更易讀的堆疊跟蹤和程式碼幀。

警告：--debug-prerender 僅用於開發環境中的除錯。請勿將使用 --debug-prerender 生成的構建部署到生產環境，因為它可能會影響效能。

構建特定路由

你可以使用 --debug-build-paths 選項僅構建 App 和 Pages Router 中的特定路由。這對於處理大型應用程式時加快除錯速度很有用。--debug-build-paths 選項接受逗號分隔的檔案路徑並支援 glob 模式。

# Build a specific route
next build --debug-build-paths="app/page.tsx"
 
# Build more than one route
next build --debug-build-paths="app/page.tsx,pages/index.tsx"
 
# Use glob patterns
next build --debug-build-paths="app/**/page.tsx"
next build --debug-build-paths="pages/*.tsx"

更改預設埠

預設情況下，Next.js 在開發期間和使用 next start 時使用 https://:3000。預設埠可以使用 -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://: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 建立本地信任的證書。在生產環境中，請使用受信任機構頒發的正式證書。

配置下游代理的超時

當 Next.js 部署在下游代理（例如 AWS ELB/ALB 等負載均衡器）後面時，重要的是配置 Next.js 底層 HTTP 伺服器的 keep-alive 超時 大於 下游代理的超時時間。否則，一旦給定 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