部署你的 Astro 網站至 Cloudflare Pages

你可以將你的 Astro 項目部署在 Cloudflare Pages，一個供前端開發人員協作和部署靜態（JAMstack）或 SSR 網站的平臺。

本指南包含：

如何使用 Git 部署一個站點
如何使用 Wrangler 部署網站
如何部署 SSR 網站

前提條件

開始之前，你需要：

一個 Cloudflare 帳號，如果還沒有的話，可以在過程中建立免費的 Cloudflare 帳號
把程式碼推到 Github 或者 GitLab 儲存庫

如何使用 Git 部署網站

在 Cloudflare Pages 建立新專案
將程式碼推到 git 倉儲（GitHub、GitLab）
登入 Cloudflare Dashboard 並在 Account Home > Workers & Pages > Overview 中選擇你的帳號
選擇 Create application，接著選 Pages 標籤，最後選 Connect to Git 選項。
選擇你想部署的 git 專案並點選 Begin setup。
使用以下的建構設定：
- Framework preset: Astro
- Build command: npm run build
- Build output directory: dist
點選 Save and Deploy 按鈕。

如何使用 Wrangler 部署網站

安裝 Wrangler CLI。
使用 wrangler login 登入 Cloudflare 帳號並授權 Wrangler。
執行你的建構命令。
使用 npx wrangler pages deploy dist 部署。

# 安裝 Wrangler CLI（命令列）
npm install -g wrangler
# 透過 CLI 登入 Cloudflare 帳號
wrangler login
# 執行你的建構命令
npm run build
# 建立新的部署
npx wrangler pages deploy dist

上傳完所有檔案後，Wrangler 會提供一個預覽網址讓你檢查網站。登入 Cloudflare Pages 儀表板時，你就會看到新專案。

使用 Wrangler 在本地啟用預覽

要使預覽正常運作，你必須安裝 wrangler

pnpm add wrangler --save-dev

然後就可以將預覽指令碼從 Astro 的內建預覽命令更新為 wrangler 了：

"preview": "wrangler pages dev ./dist"

如何部署 SSR 網站

你可以使用 @astrojs/cloudflare 轉接器 (EN)將 Astro SSR 站點部署到 Cloudflare Pages。

請按照以下步驟設定轉接器。完成後，你可以使用上述文件中的任何方法進行部署。

快速安裝

使用以下 astro add 命令新增 Cloudflare 轉接器以在你的 Astro 專案中啟用 SSR。這將安裝轉接器並一併對 astro.config.mjs 進行適當的更改。

npx astro add cloudflare

手動安裝

如果你想要手動安裝轉接器，請完成以下兩個步驟：

使用你喜歡的套件管理器將 @astrojs/cloudflare 加到專案的相依套件中。如果你使用 npm 或不確定是哪個管理器，請在終端機執行：
終端機視窗
```
npm install @astrojs/cloudflare
```

將以下內容新增到 astro.config.mjs 檔案中：

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare()
});

進一步了解 Astro 的 SSR（伺服器端算繪） (EN)。

故障排除

客戶端 hydration

Cloudflare 的 Auto Minify（自動壓縮）功能可能導致客戶端 hydration 失敗。如果你在控制檯中看到 Hydration completed but contains mismatches，請確保在 Cloudflare 設定中停用 Auto Minify。

Node.js runtime API

如果你用 Cloudflare SSR 轉接器 (EN) 的隨需算繪建立專案，而伺服器在建構時失敗，出現如 [Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node. 的錯誤資訊：

這意味著你在伺服器端環境中使用的某個套件或匯入與 Cloudflare runtime API 不相容。
如果你直接匯入 Node.js runtime API，請參考 Astro 關於 Cloudflare 的 Node.js 相容性 (EN)文件，瞭解如何進一步解決這個問題。
如果你匯入的套件中包含 Node.js runtime API，請檢查該套件的作者是否支援 node:* 的匯入語法。如果不支援，你可能需要找到其他替代套件。