Wrangler secret bulk 怎麼用？批次更新、刪除 Cloudflare Workers Secrets

JSON 的三種動作#

先建立只存在本機或 CI 暫存區的 secrets.json，不要把真實值貼進文章、Issue 或 repository：

1
{
2
  "API_BASE_URL": "https://api.example.com",
3
  "UPSTREAM_TOKEN": "replace-with-a-real-value-locally",
4
  "OLD_TOKEN": null
5
}

JSON 中的值有三種意義：

null 是刪除訊號，不是「把值設成空字串」。如果應用程式需要空值，先確認它和刪除 secret 在 runtime 的行為不同，再決定是否真的要提交這個操作。

執行 wrangler secret bulk#

Worker 名稱可以從 Wrangler 設定檔取得，也可以在命令列明確指定：

1
npx wrangler secret bulk secrets.json --name example-worker

如果要從標準輸入提供 JSON，也可以使用：

1
npx wrangler secret bulk < secrets.json

先確認目前登入的 Cloudflare account、Worker 名稱和 environment，再執行命令。這不是只更新本機檔案的操作，錯誤的 --name 或 profile 可能把同一批 secret 寫到另一個 Worker。

在 macOS 或 Linux 的本機暫存檔，可以先縮小檔案讀取權限：

1
chmod 600 secrets.json

這只能降低同一台機器上其他使用者讀取檔案的機會，不能取代 CI secret、磁碟加密、刪除暫存檔和 token 輪替。

.env 可以批次更新，但不能用來刪除#

如果現有部署流程已經使用 dotenv 格式，可以改用：

1
API_BASE_URL=https://api.example.com
2
UPSTREAM_TOKEN=replace-with-a-real-value-locally

Cloudflare 文件把 wrangler secret bulk 的輸入定義為 JSON 或 .env。但兩者的刪除能力不同：JSON 可用 null 刪除，.env 不支援刪除。因此需要清理舊 secret 時，不要在 .env 留一個空白值期待它會被刪除，應改用只含刪除項目的 JSON。

不論輸入格式，都要把 secret 檔加入 .gitignore，並在執行前檢查：

1
git status --short --ignored
2
rg -n 'API_KEY|TOKEN|PASSWORD|SECRET' secrets.json .env.production 2>/dev/null

第二個命令只適合在本機確認檔案內容；不要把輸出貼到公開的 CI log。若 repository 已經誤追蹤檔案，先依團隊的憑證外洩流程輪替值，再處理 Git 歷史，不要只刪掉工作樹檔案。

和部署一起上傳：使用 --secrets-file#

如果你想讓程式碼與這次 secret 變更使用同一個部署流程，可以把同格式檔案交給：

1
npx wrangler deploy --secrets-file .env.production
2
npx wrangler versions upload --secrets-file secrets.json

Cloudflare 文件說明，這兩個旗標接受和 wrangler secret bulk 相同的 JSON 或 .env 格式；檔案沒有列出的 secrets 會保留在前一個版本。這個方式適合 CI 的版本上傳，但仍要把檔案由 CI secret 管理器在 job 執行時產生，避免提交到 repository。

如果只是本機開發，別把 production secret bulk 檔當成 .dev.vars。本機應依 Cloudflare Workers .dev.vars、.env 與 secrets.required 的邊界選擇一種載入方式；遠端 Worker 的 Secrets 與本機 dotenv 是兩個不同的生命週期。

批次變更前的最小檢查#

我會把一次批次操作拆成以下順序：

1. 先確認 Cloudflare account、Worker 名稱與目前部署環境。
2. 以不含真實值的範例檔驗證 JSON 結構，確認 null 只出現在預期刪除項目。
3. 由 CI secret 或本機安全檔案注入真正值，不把它寫入 Git。
4. 執行後用 wrangler secret list 只檢查名稱與類型，不嘗試讀回 secret 值。
5. 執行 Worker 的健康檢查與一條需要新 secret 的測試路徑。

批次的價值是一次提交一組變更，不是讓人跳過 review。特別是刪除項目，先保留一份受保護的變更紀錄，才能在誤刪後判斷需要重新建立哪些名稱。

結論：用 JSON 表達刪除，用部署旗標對齊版本#

wrangler secret bulk 最容易記的規則是：字串代表新增或更新、null 代表刪除、未列出代表保留；而部署時的 --secrets-file 可以把同一種輸入接到版本上傳流程。先把 account、Worker、環境和檔案來源固定，再執行批次，才不會把便利的 CLI 變成跨環境寫錯 secret 的捷徑。

常見問題#