Redirect API 與規則即程式碼：用 CI/CD 管好 URL 變更

很多轉址一開始只是小修正：商品 URL 改了，說明文件搬了，活動頁換了 slug，有人在 next.config.js、Cloudflare、CMS 外掛或 Nginx 裡加一條規則。

規則少時還可以。到了網站搬遷、網域轉移、Shopify/WordPress/headless 改版、跨境電商、私域 QR code、KOL 連結、廣告投放和合作夥伴流量，轉址就不再是順手設定。

一條轉址規則會決定舊連結、搜尋流量、付費點擊、email、QR code、affiliate 連結與文件地址最後到哪裡。這是正式環境流量設定。

更穩的做法，是把 redirect rules 當成可發布設定：規則結構化，CI 驗證，預發環境展示真實行為，production 發布 versioned snapshot，並且在流量切換前準備 rollback。

為什麼轉址要進發布流程

工程團隊已經會審查環境變數、資料庫 migration、feature flag 和 middleware。會影響 SEO、投放、客服與收入的轉址，也應該進同一套流程。

脆弱的流程通常長這樣：

• SEO 維護一張 redirect map
• 工程把部分規則複製到 app config
• Marketing 在另一個工具改活動目的地
• CMS 外掛產生隱藏規則
• CDN 負責 host normalization
• 出問題時沒有人知道哪一層生效

規則即程式碼的價值，不是強迫所有東西用某個格式，而是讓 redirect map 變成可審查的發布資產。它可以是 YAML、JSON、Terraform、CSV 或 API payload。重點是有 owner、有測試、有回滾。

規則不能只有 source 和 destination

old_url 和 new_url 可以建立 redirect，但不足以安全營運。

比較好的規則契約會寫清楚意圖：

{
  "source": "/old-pricing",
  "destination": "/pricing",
  "status": 301,
  "match": "exact",
  "queryPolicy": "preserve_allowlist",
  "preserveQuery": ["utm_source", "utm_medium", "utm_campaign", "gclid"],
  "owner": "growth",
  "reason": "pricing page consolidation",
  "expiresAt": null
}

搬站、電商與活動場景還會需要 priority、locale、country、device、batch、review status 和 fallback。

Google 對 redirects 的說明也圍繞意圖：這次移動是臨時還是永久，搜尋結果應該顯示哪個 URL。CI 不能代替團隊做業務判斷，但可以擋掉明顯危險的組合。

API 同步比人工複製可靠

轉址常常不是從 repository 產生的。CMS 改 slug，商品下架，文件版本更新，SEO 代理商交付 migration map，合作夥伴需要 branded link，營運希望快速切 fallback。

如果每個來源都靠人工匯入，規則很快會漂移。

Redirect API 給團隊一個清楚邊界：

Cloudflare 可以透過 Rulesets API 建立 redirect rule。Next.js 和 Vercel 也支援設定式 redirects。這些都是執行層。真正困難的是執行層之外的治理：驗證、歸屬、預發、analytics 與 rollback。

CI 應該檢查什麼

轉址 CI 不應該只檢查 JSON 能不能 parse，而要驗證行為。

值得檢查：

• source path 重複
• destination 格式錯誤
• 缺 owner、reason 或 status
• wildcard 或 regex 覆蓋 exact rule
• 有到期時間的活動卻用了永久 status
• 目標頁回 404、410、5xx 或意外 redirect
• redirect chain 過長
• loop
• UTM、click ID、coupon、partner ID 遺失
• country、device、header、query 條件沒有 fallback
• 與其他 batch 衝突

高風險 URL 可以跑 request matrix：

source=/old-pricing
country=TW
device=desktop
query=?utm_source=google&gclid=test
expectedStatus=301
expectedDestination=/pricing?utm_source=google&gclid=test

這樣上線前就能知道這個 request 會去哪裡。

預發環境要顯示最終路由

轉址 staging 應該回答一個問題：這條 URL 帶著這個 request context，在 production 會發生什麼？

最好顯示：

• 命中的 rule
• status code
• final destination
• query handling
• condition result
• competing rules
• chain length
• owner 和 batch
• 與目前 published snapshot 的 diff

GitHub Actions environments 可以在 deployment 前要求 reviewer。轉址也可以採用同樣模式：CI 驗證，staging 給證據，production publish 等待正確負責人批准。

Rollback 是產品需求

回滾一條 redirect 不應該代表半夜重新部署 origin app。

保留已發布 snapshot。替 import batch 加 tag。把臨時活動規則和永久搬遷規則分開。緊急 override 必須可見，不能藏在 CDN 或 app middleware 裡。

如果規則會影響搜尋、廣告、客服或收入，rollback 就不是附加功能。

UrlEdge 適合哪裡

UrlEdge 適合想自動化 redirect，但不想每次 URL 變更都部署 origin app 的團隊。

• API 用於 domains、rules、publishing 和 automation
• Redirect Management 用於 ownership、analytics、snapshots 和 rollback
• Bulk URL Management 用於 migration map 和大量匯入
• Advanced Redirect Rules 用於 wildcard、regex、query 和條件
• Redirect Checker 用於路由和狀態碼 QA
• Collaboration 用於 SEO、Marketing、平台和代理商之間的審批

屬於 app 本身的小 redirect 可以留在 app config。簡單 host normalization 可以交給 CDN。只要規則需要審查、證據、自動化和快速恢復，就該考慮 Redirect API 與 rules as code。

FAQ

什麼是 redirect rules as code？

把轉址規則放在結構化、可審查的格式裡，並經過驗證、預發、發布與回滾流程。

所有轉址都要放 Git 嗎？

不需要。穩定的 migration rule 適合 Git。來自 CMS、電商目錄、合作夥伴與內部工具的動態規則更適合 API sync。

CI/CD 可以直接發布 redirect 嗎？

可以，但前提是有驗證、預發證據、權限控制、高風險變更審批和 rollback。

參考資料

• Google Search Central: Redirects and Google Search
• Cloudflare Rules docs: Create a redirect rule via API
• Next.js docs: next.config.js redirects
• GitHub Docs: Managing environments for deployment