Cloudflare Workers で API キーや Webhook シークレットを使うとき、wrangler secret put でシークレットを登録します。これを忘れたまま wrangler deploy してしまうと、本番でリクエストが来てから「あれ、API キーがない」と気づくことがあります。

2026 年 3 月にリリースされた secrets configuration property を使うと、wrangler.json に必須シークレット名を宣言しておくだけで、未設定の状態でデプロイすると wrangler 側でエラーにしてくれるようになります。実際に手元の Worker で試したので、その記録を残しておきます。

設定したこと

wrangler.json に secrets.required を追加して、必須のシークレット名を 2 つ宣言しました。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "jpstripes-connect-2026-webhook",
  "main": "src/index.ts",
  "compatibility_date": "2026-06-01",
  "compatibility_flags": ["nodejs_compat"],
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1
  },
  "secrets": {
    "required": ["STRIPE_API_KEY", "STRIPE_WEBHOOK_SECRET"]
  }
}

詳しい設定項目は Wrangler Configuration の secrets セクションを参照してください。

シークレット未設定の状態でデプロイしたら

この状態で pnpm run deploy(wrangler deploy) を実行すると、デプロイが走る前に次のエラーで止まりました。

✘ [ERROR] The following required secrets have not been set: STRIPE_API_KEY, STRIPE_WEBHOOK_SECRET
  Use `wrangler secret put <NAME>` to set secrets before deploying.
  See
  https://developers.cloudflare.com/workers/configuration/secrets/#secrets-on-deployed-workers
  for more information.
🪵  Logs were written to "/Users/okamotohidetaka/.wrangler/logs/wrangler-2026-06-05_14-32-25_189.log"
 ELIFECYCLE  Command failed with exit code 1.

必須宣言したシークレット名がそのままエラーに出てきて、wrangler secret put <NAME> を案内してくれます。デプロイが完了してから本番リクエストで気づくのではなく、wrangler deploy を叩いた時点で止まるので、CI に組み込めば失敗ジョブとして検知できます。

シークレットを登録して再デプロイ

エラーメッセージに従って、シークレットを 2 つ登録しました。

% pnpm exec wrangler secret put STRIPE_API_KEY
 ⛅️ wrangler 4.98.0
───────────────────
✔ Enter a secret value: … ***********
🌀 Creating the secret for the Worker "jpstripes-connect-2026-webhook"
✔ There doesn't seem to be a Worker called "jpstripes-connect-2026-webhook". Do you want to create a new Worker with that name and add secrets to it? … yes
🌀 Creating new Worker "jpstripes-connect-2026-webhook"...
✨ Success! Uploaded secret STRIPE_API_KEY

% pnpm exec wrangler secret put STRIPE_WEBHOOK_SECRET
 ⛅️ wrangler 4.98.0
───────────────────
✔ Enter a secret value: … ****
🌀 Creating the secret for the Worker "jpstripes-connect-2026-webhook"
✨ Success! Uploaded secret STRIPE_WEBHOOK_SECRET

1 回目の wrangler secret put では、まだ Worker 自体がデプロイされていなかったので「該当する Worker がないけど作るか?」と確認が出てきます。yes で先に Worker を作ってから、シークレットだけ先行登録される流れです。

その後改めて pnpm run deploy を実行すると、今度はデプロイが完走しました。

% pnpm run deploy
> [email protected] deploy /Users/okamotohidetaka/development/my-services/apis/jpstripes-connect-2026-webhook
> wrangler deploy
 ⛅️ wrangler 4.98.0
───────────────────
Total Upload: 255.93 KiB / gzip: 49.23 KiB
Worker Startup Time: 19 ms
Uploaded jpstripes-connect-2026-webhook (2.17 sec)
Deployed jpstripes-connect-2026-webhook triggers (1.05 sec)

secrets.required で宣言したシークレットがすべて登録されている状態になったので、デプロイ前のチェックを通過してくれました。

おわりに

wrangler.json に必須シークレット名を書いておけば wrangler 側で止めてくれるので、新規 Worker のテンプレートに secrets.required を入れておく運用にしてみようと思います。

検証時のバージョンは wrangler 4.98.0 です。機能自体は 2026 年 3 月のリリースなので、それ以前のバージョンを使っている場合はアップデートが必要です。詳しい挙動は Changelog と Wrangler Configuration のドキュメントを参照してみてください。