Cloudflare Workers KV API 路徑即將淘汰：如何從 workers/namespaces 遷移

先看新舊 endpoint 對照#

所有 endpoint 的共同變化如下：

這不是把 Workers binding 名稱改掉。Worker 程式碼裡的 env.KV.get()、env.KV.put() 等 binding API 不會因為 REST 管理路徑棄用，就自動變成另一個 binding；本次要盤點的是直接組 Cloudflare API URL 的外部整合。

先從 repository 和部署設定找出舊路徑#

在 repository 根目錄執行：

1
rg -n \
2
  --glob '!node_modules/**' \
3
  --glob '!dist/**' \
4
  'workers/namespaces' \
5
  .

接著再搜尋較寬的關鍵字，避免 URL 是由多段字串組成：

1
rg -n \
2
  --glob '!node_modules/**' \
3
  --glob '!dist/**' \
4
  'workers/namespaces|storage/kv/namespaces|CLOUDFLARE_API_TOKEN|namespace_id' \
5
  .

要特別查看 .github/workflows/、Terraform／Pulumi 設定、shell script、後端 SDK wrapper 和監控工具。搜尋結果是盤點清單，不是可以直接批次取代的授權；先確認每個命中點是否真的在呼叫 Workers KV API。

先用讀取請求驗證新的 base path#

準備好帳號 ID、API token 後，可以先用 list namespaces 做不涉及資料寫入的 smoke test：

1
export ACCOUNT_ID='你的 Cloudflare account ID'
2
export CLOUDFLARE_API_TOKEN='只在目前 shell 使用的 token'
3

4
curl --fail-with-body \
5
  -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
6
  "https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/storage/kv/namespaces"

這個請求要在測試帳號或已確認權限的環境執行。不要把 token 寫進 shell script、Markdown、CI log 或文章範例的固定值；上面的環境變數只是示意名稱。

若整合原本使用 API token 以外的認證方式，先回到 Cloudflare API authentication 文件確認該帳號的合法 scheme。路徑替換不會自動修正權限、account scope 或 URL encoding 問題。

value key 仍要處理 URL encoding#

替換 namespace 這一段不會改變 key 的語意，但 key_name 仍是 URL path 的一部分。若 key 包含空白、斜線、問號或非 ASCII 字元，呼叫端應沿用原本的 URL encoding 策略，不要直接把原始 key 拼到 URL：

1
const path = [
2
  'accounts',
3
  accountId,
4
  'storage',
5
  'kv',
6
  'namespaces',
7
  namespaceId,
8
  'values',
9
  encodeURIComponent(keyName),
10
].join('/');
11

12
const response = await fetch(`https://api.cloudflare.com/client/v4/${path}`, {
13
  headers: {
14
    Authorization: `Bearer ${token}`,
15
  },
16
});

如果原本的 client 已經負責 encoding，遷移時不要為了換 path 又重複 encode 一次。最安全的做法是用一個已知包含特殊字元的測試 key，對照新路徑的讀取結果與原本的預期。

把遷移拆成盤點、替換、回歸三關#

這幾種改法看似合理，其實會擴大風險#

• 只改主 repository，忘記 CI 或內部工具：部署後還是可能有 cron、管理後台或 migration script 呼叫舊路徑。
• 把 binding API 一起改名：REST API 路徑和 Worker binding 是不同層，不能把 env.KV 任意改成 env.storage。
• 直接全域取代 namespaces：Cloudflare 其他產品或 API 可能也使用相同字串，應以完整 path 和呼叫上下文判斷。
• 用新增 namespace 來測 production：建立、改名與刪除 namespace 都會改變帳號資源，先用 read-only list 做第一關。
• 把 deadline 寫成立刻失效：Cloudflare 的公告區分 deprecated date 和 end-of-life date；文章查核日是 2026-08-05，正式停用日期仍以官方文件為準。

結論：這次是路徑遷移，不是資料搬家#

Workers KV legacy namespace routes 的遷移重點，是把 /workers/namespaces/ 改成 /storage/kv/namespaces/，並確認所有外部 API 呼叫都使用新 path。因為參數和 response payload 維持不變，最值得投入的時間是完整盤點與 method-level 回歸，而不是重寫 KV 資料模型。

常見問題#