CodFlow 店面 — Vercel 部署手冊

cod-astro/theme01 是 CodFlow（Astro 7）的顧客面向店面主題。雖然 CodFlow 後端 (cod-server) 和商家儀表板 (cod-client-astro) 運行在 Cloudflare Workers 上（使用 D1、R2 和 KV），但店面支援動態部署目標（DEPLOY_TARGET=vercel 或 DEPLOY_TARGET=cloudflare）。

將店面部署到 Vercel 通常是較好的選擇，因為：

解決 Cloudflare Error 1042（Worker 間封鎖）： 當 cod-server 部署在免費的 *.workers.dev 子網域且未使用自訂網域時，Cloudflare 會封鎖同樣在 *.workers.dev 上的另一個 Cloudflare Worker 對其發起請求。Vercel 在 Cloudflare 內部網路之外運行，因此店面可以順利存取 *.workers.dev 上的 cod-server，無需自訂網域。
慷慨的全球邊際頻寬： Vercel 提供慷慨的頻寬和 Edge CDN 快取，適合店面流量。
自動預覽部署： 每個 Git 分支/PR 都可以擁有自己的預覽 URL，方便測試主題變更。

必要的環境變數

部署前，請收集以下值：

變數	說明	範例
`DEPLOY_TARGET`	必要。告訴 `astro.config.mjs` 使用 `@astrojs/vercel`	`vercel`
`COD_SERVER_URL`	必要。已部署的 `cod-server` API 的基礎 URL	`https://api.yourdomain.com` 或 `https://codflow-server.<account>.workers.dev`
`STORE_API_KEY`	必要。與 D1 中初始化的金鑰相符的原始商店 API 金鑰	在 `codflow-setup` 步驟 4 中產生
`MEDIA_DOMAIN`	選填。 R2 圖片 CDN 的自訂網域	`media.yourdomain.com`

[!IMPORTANT] STORE_API_KEY 是機密資料。它在伺服器端的 SSR 路由和 API 代理中使用。切勿在客戶端套件中暴露它。

部署方式

選擇方法 1 (Vercel CLI) 進行自動化/終端機部署，或方法 2 (Vercel Dashboard / Git) 進行來自 GitHub 的持續部署。

方法 1：透過 Vercel CLI 部署（推薦用於 AI 代理）

1. 先決條件

確保可透過 npx vercel 使用 Vercel CLI（或已全域安裝）。
檢查驗證狀態：
```
npx vercel whoami
```
如果尚未登入：
- 如果瀏覽器可用：npx vercel login
- 如果是無頭環境/CI：在環境中設定 VERCEL_TOKEN（export VERCEL_TOKEN="<token>"）。

2. 設定並連結專案

切換到店面目錄：

cd cod-astro/theme01

執行初始設定：

npx vercel link

依照互動提示操作（或在非互動式工作階段中使用旗標）：

連結到現有專案？No（如果連結現有專案則選 Yes）
專案名稱：<project>-storefront（例如 mystore-storefront）
你的程式碼在哪個目錄？./

3. 設定環境變數

使用 CLI 新增必要的生產環境變數：

# 1. 部署目標
printf "vercel" | npx vercel env add DEPLOY_TARGET production

# 2. 後端 API URL（必須以 https:// 開頭）
printf "https://<your-cod-server-domain>" | npx vercel env add COD_SERVER_URL production

# 3. 商店 API 金鑰
printf "<your-raw-store-api-key>" | npx vercel env add STORE_API_KEY production

# 4. 選填：媒體網域（如果已設定 R2 自訂網域）
printf "<media.yourdomain.com>" | npx vercel env add MEDIA_DOMAIN production

（選填：如果你打算使用預覽分支，也可以將它們新增到 preview 和 development 環境）。

4. 建置並部署到生產環境

使用 Vercel 適配器執行生產部署：

cd cod-astro/theme01
npx vercel --prod

Vercel 會上傳專案、執行 npm run build:vercel（或使用 DEPLOY_TARGET=vercel 執行 astro build）、編譯 SSR 無伺服器/邊緣函式，並提供上線的生產 URL（例如 https://<project>-storefront.vercel.app）。

方法 2：透過 Vercel Dashboard 部署（Git 整合）

在連結 GitHub / GitLab / Bitbucket 儲存庫時使用此方法：

在 Vercel 中匯入儲存庫：
- 在 Vercel Dashboard 中，點擊 Add New... → Project。
- 選取 codflow-os 儲存庫。
設定專案設定：
- 專案名稱： 例如 codflow-storefront
- 框架預設： Astro
- 根目錄： 點擊 Edit 並選擇 cod-astro/theme01。勾選選項 "在建置步驟中包含根目錄之外的原始碼檔案"（需要此選項，因為工作區依賴項會解析到根目錄的 node_modules）。
- 建置指令： 切換 Override 並設定為：
```
npm run build:vercel
```
  （如果已在環境變數中設定 DEPLOY_TARGET=vercel，則保留預設的 astro build）。
- 輸出目錄： 保留預設值（.vercel/output）。
- 安裝指令： 保留預設值（npm install / 根目錄工作區安裝）。
設定環境變數： 在 Environment Variables 下，新增：
- DEPLOY_TARGET = vercel
- COD_SERVER_URL = https://<your-cod-server-domain>
- STORE_API_KEY = <your-raw-store-api-key>
- MEDIA_DOMAIN = <media.yourdomain.com>（選填）
部署：
- 點擊 Deploy。Vercel 會建置工作區，使用 @astrojs/vercel 打包 Astro 網站，並分配一個生產 URL。

驗證與冒煙測試

部署完成後，對上線的 Vercel URL 執行以下檢查：

目標	測試指令 / 動作	預期結果
首頁	`curl -s -o /dev/null -w "%{http_code}" https://<storefront-url>`	`200`（HTML 回應）
目錄 SSR	在瀏覽器中開啟 `https://<storefront-url>/`	商品載入，包含圖片、價格和標題
商品詳情	開啟 `https://<storefront-url>/product/<slug>`	商品頁面呈現，包含結帳/訂購表單
購物車 / 訂單流程	提交測試訂單（或測試彈出視窗）	訂單成功註冊，並顯示感謝頁面

透過終端機測試：

# 確認首頁回傳 200 OK
curl -s -I "https://<your-storefront>.vercel.app" | head -n 5

# 確認透過店面代理的 API 連線
curl -s "https://<your-storefront>.vercel.app/api/cart/validate" \
  -H "Content-Type: application/json" \
  -d '{"items":[]}'
# 預期回傳有效的 JSON 回應

自訂網域設定

若要為 Vercel 店面附加自訂網域：

在 Vercel Dashboard 中：專案 → Settings → Domains。
輸入你的網域（例如 store.yourdomain.com 或 yourdomain.com）。
設定 DNS 記錄：
- 針對子網域（store.yourdomain.com）：新增指向 cname.vercel-dns.com 的 CNAME 記錄。
- 針對頂級網域（yourdomain.com）：新增指向 76.76.21.21 的 A 記錄。
等待 SSL 憑證核發（透過 Let's Encrypt 自動進行）。

排錯

問題	原因	解決方案
建置失敗：`Cannot find module '@astrojs/vercel'`	`cod-astro/theme01` 中缺少相依項	在儲存庫根目錄執行 `npm install @astrojs/vercel --workspace=cod-astro-theme01`。
建置產出 Cloudflare 輸出而非 Vercel 輸出	`DEPLOY_TARGET` 未設為 `vercel`	確保 Vercel 環境變數中存在 `DEPLOY_TARGET=vercel`，或執行 `npm run build:vercel`。
店面載入但顯示空產品 / 錯誤橫幅	`COD_SERVER_URL` 不正確或無法連線	確認 `COD_SERVER_URL` 包含 `https://` 前綴並與線上 API Worker 相符。驗證 `curl https://<api-url>/api/docs` 回傳 200。
訂單失敗，顯示 401 Unauthorized	`STORE_API_KEY` 不符	Vercel 中的 `STORE_API_KEY` 值必須與 `codflow-setup` 步驟 5 中寫入 D1 資料庫的金鑰相符。請重新檢查或更新 Vercel 中的密碼。
Monorepo 建置無法解析共用套件	Vercel 根目錄設定錯誤	如果使用 Git 整合，請確保在 Vercel 專案設定中啟用 "包含根目錄之外的原始碼檔案"，或在 `cod-astro/theme01` 內部透過 `npx vercel` 部署。
Node.js 版本警告：`Node.js 26 is not supported`	Vercel 無伺服器函式最多支援 Node 24	在 Node 26 開發機器上是正常警告；Vercel 會在其雲端函式中自動執行 Node 24。
圖片未從 R2 載入	`MEDIA_DOMAIN` 設定錯誤或缺少 CORS	確認已設定 `MEDIA_DOMAIN`（僅主機名稱，不含 `https://`）。確保 R2 儲存桶的 CORS 政策允許來自 Vercel 網域的請求。

CodFlow 店面 — Vercel 部署腳本