Jul 29, 2026

不要相信 API 的「成功」：Cloudflare Pages 部署踩坑實錄與除錯心法

在現代的網頁開發中，將靜態網站自動化部署到 CDN 邊緣節點（Edge）已經是標準配備。最近，我著手將一個 Astro 靜態部落格透過 GitHub Actions 部署到 Cloudflare Pages（採用 Direct Upload 模式），並將網域與 DNS 紀錄都交由同一個 Cloudflare 帳號集中管理。

本以為這會是一趟如同官方教學般行雲流水的旅程，然而，現實卻狠狠地給我上了一課。在建置與部署的過程中，我遭遇了一連串令人抓狂的延遲與非預期行為，而這一切的罪魁禍首，竟然是系統所回傳的「成功」訊息。

那些騙人的 200 OK (The Problem)

整個部署流程被大幅拖延，最主要的原因在於：部署工具與 API 頻繁地回傳了「成功」的狀態指示，但底層的操作卻是失敗或尚未完成的。這就像是餐廳服務生告訴你「餐點已經好了」，結果廚房連火都還沒開。

具體來說，我遇到了以下幾個關鍵的阻礙：

偽裝成空陣列的權限錯誤：在串接 API 獲取專案資訊時，因權限設定不當導致的錯誤，並沒有回傳明確的 HTTP 403 (Forbidden) 或 401 (Unauthorized)，反而優雅地回傳了一個 HTTP 200 OK，配上一個空陣列（Empty Data Array []）。這讓腳本誤以為專案不存在，進而引發後續的邏輯錯誤。
網域綁定成功，DNS 卻離奇失蹤：在設定自訂網域時，控制面板與 API 均顯示「網域綁定成功」。然而，實際去查詢 DNS 紀錄，卻發現相關的 CNAME 根本沒有被正確建立，導致網站處於無法解析的幽靈狀態。
CDN 快取造成的薛丁格狀態 (Intermittent 522 Timeouts)：即使部署完成，在存取網站時卻會遭遇間歇性的 HTTP 522 Connection Timed Out。這種時好時壞的狀態，讓人難以判斷是源伺服器（Origin Server）配置錯誤，還是單純的網路波動。

深入探討：非同步與最終一致性的陷阱

身為工程師，我們習慣依賴系統的回饋來做決策。那為什麼這些成熟的雲端服務會給出錯誤的訊號？探究其根本原因，可以歸咎於系統架構設計上的兩個深層陷阱：

1. 混淆了「請求已受理」與「狀態已確認」

許多分散式系統的 API 為了維持高可用性與低延遲，採用了非同步（Asynchronous）處理模型。當你發出部署或綁定網域的請求時，API 回傳的「成功」，僅代表「請求已成功進入佇列」，而非「操作已成功執行完畢」。系統將不同的失敗模式與非同步的過渡狀態，粗暴地簡化為統一的成功回應（Uniform Success Responses）。這種設計掩蓋了底層可能發生的細微錯誤。

2. HTTP 狀態碼無法呈現「最終一致性」

CDN 與 DNS 系統是典型的「最終一致性（Eventual Consistency）」架構。節點之間的狀態同步需要時間。傳統的 HTTP 狀態碼只能反映當下那個瞬間、某個特定節點的視角，並不能代表整個系統的全貌。這種設計導致了短暫的部署過渡狀態（Transient Deployment States），在開發者眼裡看起來就像是永久性的伺服器錯誤，進而誘導開發者朝錯誤的方向進行除錯。

解決方案與實作：重塑信任邊界

既然不能無腦相信 API 回傳的狀態碼，我們就必須改變策略：從「信任初始 API 回應」轉向「驗證最終運作狀態（Verifying Final Operational State）」。

為了徹底解決這些問題，我建立了一套更穩健的除錯與部署驗證機制，主要包含以下幾個維度：

1. 針對最終一致性的資源進行持續採樣 (Continuous Sampling)

不要只發送一次請求就決定生死。對於 DNS 或 CDN 節點更新，我們需要在自動化腳本中實作帶有指數退避（Exponential Backoff）的輪詢機制。

#!/bin/bash
# 驗證 DNS 紀錄是否生效的簡易腳本 (Continuous Sampling 範例)

DOMAIN="blog.example.com"
MAX_RETRIES=8
RETRY_COUNT=0

while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
  # 透過公共 DNS 檢查 CNAME 是否已正確指向 Cloudflare Pages
  RESULT=$(dig +short @8.8.8.8 $DOMAIN CNAME)
  
  if [ -n "$RESULT" ]; then
    echo "✅ DNS 紀錄已生效：$RESULT"
    exit 0
  fi
  
  WAIT_TIME=$((2 ** RETRY_COUNT))
  echo "⏳ 等待 DNS 傳播中... (重試 $((RETRY_COUNT+1))/$MAX_RETRIES, 暫停 ${WAIT_TIME}s)"
  sleep $WAIT_TIME
  RETRY_COUNT=$((RETRY_COUNT+1))
done

echo "❌ 驗證超時：DNS 狀態未達預期"
exit 1

2. 使用對照組隔離異常 (Control Groups)

為了解決間歇性 522 錯誤，我引入了對照組的思維。不僅僅是透過瀏覽器存取，我也同時使用 curl 直接指定不同的 Cloudflare Edge IP 進行請求，或是繞過快取（加上隨機 Query String 例如 ?t=12345），藉此釐清是全局配置錯誤，還是特定 CDN 節點尚未同步完成。

3. 跨層級的底層基礎設施驗證 (Cross-layer Validation)

當上層 API（如 Cloudflare Dashboard 或 Pages API）說「沒問題」時，我們必須下探到底層去驗證：

面對 API 回應：懷疑權限問題時，不要只看 200 OK，必須檢查 Response Payload 中的資料結構是否符合預期（防範空陣列陷阱）。
面對基礎設施：懷疑部署未上線時，先直接存取 Cloudflare Pages 自動分配的 *.pages.dev 內部網域，確認打包好的 Artifacts 確實存在且運作正常，再回過頭來檢查自訂網域與 DNS 的綁定。

結語 (Key Takeaways)

這次將 Astro 部署到 Cloudflare Pages 的踩坑經驗，再次印證了在分散式系統中「眼見不一定為憑」。作為軟體工程師與架構師，我們在設計自動化 CI/CD 流程或進行故障排除時，應該將以下原則銘記在心：

永遠驗證狀態，而非回應：API 回傳的 200 OK 只是參考，真正的成功是系統表現出符合預期的行為。
擁抱最終一致性：在撰寫基礎設施即程式碼（IaC）或自動化部署腳本時，必須將非同步等待與重試驗證機制視為標準配備。
不要被抽象層蒙蔽：當高階 API 或控制面板提供令人困惑的結果時，果斷使用底層網路工具進行跨層級的交叉比對。

保持對系統回應的健康懷疑，並建立基於「最終狀態」的驗證邏輯，才能在雲端架構的叢林中建立起真正穩健的部署流程。