wrangler kv bulk put 二進位資料損壞？先升級 4.125.0

先分清 local 與 remote#

Wrangler v4 的 KV 命令預設使用本機資料。需要操作 Cloudflare API 或正式 namespace 時，必須明確加上 --remote；只寫一個沒有旗標的命令，不能當成「一定會更新雲端」。

--binding=MY_KV 要換成 wrangler.toml 或 wrangler.jsonc 中的 KV binding 名稱；如果沒有 binding，也可以依官方命令使用 --namespace-id。不論使用哪一種方式，都把 --local 或 --remote 寫進腳本，避免日後升級 Wrangler 後因預設值誤解而寫錯地方。

如何確認自己真的遇到這個問題#

先看專案實際執行的 Wrangler，而不是只看全域安裝版本：

1
pnpm exec wrangler --version

建立一個只供測試的二進位 fixture。以下 Node.js 腳本會把檔案轉成 base64，產生 kv bulk put 需要的 JSON；不要把正式資料直接拿來做第一次驗證：

1
node - <<'NODE'
2
const fs = require('node:fs');
3
const value = fs.readFileSync('fixture.bin').toString('base64');
4
fs.writeFileSync(
5
  'fixture.json',
6
  JSON.stringify([{ key: 'fixture.bin', value, base64: true }], null, 2),
7
);
8
NODE

在受測版本上寫入 local KV：

1
pnpm exec wrangler kv bulk put fixture.json --binding=MY_KV --local

接著由 wrangler dev 中的 Worker 以 arrayBuffer 讀回 fixture.bin，比較寫入前後的長度與 SHA-256。不要用 --text 讀二進位值，因為該旗標會把結果解碼為 UTF-8 字串；即使檔案原本不是文字，驗證程式也可能因此掩蓋問題。

若想用 CLI 確認資料流程，kv bulk get 可以輸出批次結果，或先用 kv key get 列出該 key；真正的判斷仍應以 Worker 讀回的 ArrayBuffer bytes 為準。測試 namespace、--persist-to 位置和 fixture.bin 都應該是可拋棄的資料。

正確修復流程#

1
pnpm add --save-dev wrangler@^4.125.0
2
pnpm exec wrangler --version

1
pnpm exec wrangler kv bulk put fixture.json --binding=MY_KV --remote

不要把三種問題混在一起#

• 讀回 bytes 變長或內容不同：先看是不是舊版 Wrangler、base64: true、local KV，以及內容是否包含無效 UTF-8 位元組。
• 寫入了錯的 namespace：先檢查 Wrangler v4 的 local 預設和是否漏了 --remote，這不是同一個 binary corruption bug。
• 只有文字值失敗：沒有 base64 或內容是有效 UTF-8 時，官方 4.125.0 release note 描述的案例不一定適用，應另外檢查 binding、JSON 格式和權限。

這樣分層後，才不會為了修 local fixture 而誤改正式 KV，也不會把遠端 API 的權限錯誤誤判成二進位編碼問題。

常見問題#