v4
工程部署
CloudflareEdge Computing

部署到 Cloudflare

Cloudflare Pages 是目前部署 Nuxt 應用程式的最佳選擇之一。它提供了全球 CDN 加速、免費的 HTTPS 與極致的 Edge 運算效能。

為什麼選擇 Cloudflare？

極致效能

您的應用程式將運行在 Cloudflare 的 Edge Network 上，伺服器邏輯會自動複製到全球數百個節點，讓使用者永遠連線到最近的伺服器。

免費額度大方

Cloudflare Pages 提供非常大方的免費方案，包含無限的頻寬與請求次數（有一定限制但對個人專案綽綽有餘）。

Git 整合

只要將程式碼推送到 GitHub/GitLab，Cloudflare 就會自動觸發建置並部署，並提供預覽網址 (Preview URL)。

專案設定

雖然 Cloudflare 通常能自動偵測 Nuxt，但為了確保最佳相容性，我們建議在 nuxt.config.ts 中明確指定 Preset。

nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    // 明確指定使用 Cloudflare Pages 預設配置
    preset: 'cloudflare-pages'
  }
})

Node.js 版本相容性

請確保您的專案在 Cloudflare 建置環境中使用 Node.js 18+ 或 20+。 您可以在專案根目錄建立 .nvmrc 檔案來指定版本。

Git 自動部署

這是最推薦的部署方式。您只需要在 Cloudflare Dashboard 點擊幾下即可完成。

Build Settings (關鍵設定)

在設定專案時，請務必確認以下三個欄位設定正確，否則可能會導致部署失敗或頁面空白。

Framework Preset
Nuxt.js
Build Command
pnpm generate
或 npm run generate
Build Output Directory
dist
⚠️ 使用 generate 時請設為 dist
  1. 將您的 Nuxt 專案推送到 GitHub 或 GitLab。
  2. 登入 Cloudflare Dashboard，進入 Workers & Pages。
  3. 點擊 Create application > Pages > Connect to Git。
  4. 選擇您的儲存庫 (Repository)。
  5. 填入上方的 Build Settings 數值。
  6. 點擊 Save and Deploy。

常見問題排除

部署成功但頁面空白 (Blank Page)

這通常是因為 Build Output Directory 設定錯誤。

  • 若使用 pnpm generate (SSG)，輸出目錄應為 dist。
  • 若使用 pnpm build (SSR/Hybrid)，輸出目錄應為 .output/public。
  • 請回到 Settings > Build & deployments 修改設定並重新部署。

500 Server Error

如果在執行 API 請求時發生錯誤，請檢查：

  • 是否在 nuxt.config.ts 中設定了 nitro.preset: 'cloudflare-pages'。
  • 環境變數是否已在 Cloudflare Dashboard 中設定 (Settings > Environment variables)。