起きたこと: デプロイ結果を「成功表示」で終わらせない
2026年7月24日にCloudflare公式資料とこのブログのデプロイ ヘルパーを照合しました。
公式仕様では、wrangler deployは新しいWorker バージョンを作り、通常はそのまま100% trafficへデプロイします。
routesを外した設定を渡しても、アップロード-onlyのwrangler versions uploadへ変わるわけではありません。
このブログでは、既存custom domainルートを変更できない限定トークンでroutine デプロイするため、ビルド後の設定からroutesだけを外します。
そのうえでヘルパーは、wrangler deployが返したバージョン IDを特定し、同じIDをwrangler versions deployで100%へ明示し直し、wrangler deployments list --jsonで確認します。
これはプロジェクト固有の保守的な手順であり、一般のwrangler deployがアップロードだけで終わるという主張ではありません。
Worker デプロイ、バージョン ID特定、100% traffic確認、別工程のHTTP確認を分離した手順*図: Worker deploymentの確認と、本番custom domainのHTTP確認は別の証拠です。このヘルパーが自動確認するのはdeployment JSONまでで、live HTTP確認は後続工程です。*
このヘルパーの実行順
実コードは--configと--nameも渡しますが、中心となる順序は次の通りです。
bash
wrangler versions list --json # deploy前のversion集合
wrangler deploy # version作成 + defaultの100% deploy
wrangler versions deploy \
--version-id <ID> --percentage 100 --yes
wrangler deployments list --json # 最新deploymentを確認
この引数は、プロジェクトで使うWrangler 4.94.0のCLIのヘルプとも一致します。
本当にアップロードとデプロイを分離したい場合の公式コマンドはwrangler versions uploadです。
Cloudflare公式資料では、ルート・domain・cron トリガーの変更は別にwrangler triggers deployを使うよう案内されています。
バージョン ID フォールバック: 「最新」ではなく一意差分
wrangler deployの人が読む形式の出力にCurrent Version ID: <uuid>があれば、厳格なUUID patternで取得します。
ただし、表示形式が変わった場合にデプロイ後の「最新バージョン」を採用してはいけません。
同時に別のアップロードが走ると、無関係なバージョンを100%へpromoteする危険があるためです。
ヘルパーはデプロイ前のwrangler versions list --jsonを保存し、必要な場合だけデプロイ後にも取得します。
前後集合の一意差分が、妥当なUUID 1件だけなら採用します。
差分が0件または複数ならバージョンを推測せず失敗します。
js
function parseUploadedVersionId(beforeJson, afterJson) {
const before = new Set(
JSON.parse(beforeJson).map((entry) => entry?.id),
);
const after = JSON.parse(afterJson);
const created = after.filter(
(entry) => isUuid(entry?.id) && !before.has(entry.id),
);
return created.length === 1 ? created[0].id : null;
}
100% trafficの確認: 確認できなければ失敗
wrangler versions deployの終了コードだけでは完了にしません。
wrangler deployments list --jsonを読み、時刻順で最新のdeploymentに対象バージョンが100%で含まれることを確認します。
JSONが壊れている、deploymentが空、対象IDがない、percentageが100でない場合はすべて失敗です。
js
function isVersionActiveAtFullTraffic(jsonText, versionId) {
const deployments = JSON.parse(jsonText);
const latest = [...deployments].sort(
(a, b) => Date.parse(b?.created_on ?? 0) - Date.parse(a?.created_on ?? 0),
)[0];
const versions = Array.isArray(latest?.versions) ? latest.versions : [];
return versions.some(
(entry) => entry?.version_id === versionId && Number(entry?.percentage) === 100,
);
}
なお、この確認が証明するのはCloudflare deployment 状態です。
custom domainで新しいHTMLやassetが返ることまでは証明しないため、デプロイ後に本番URLを別途HTTP・ブラウザで確認します。
Log sanitizerは補助線
ヘルパーはstdoutとstderrをそのまま転送せず、email、アカウント ID、既知の公開識別子、環境変数値などをpatternで置換します。
しかしpattern-based sanitizerは未知のcredentialや新しい出力形式まで安全を保証しません。
シークレットをlogへ出さない設計、CI側のmask、staged シークレットスキャンを前提にし、その上で偶発的な露出を減らす補助として使います。
まとめ
wrangler deployは通常、バージョン作成と100% デプロイを一度に行う- アップロード-onlyの公式コマンドは
wrangler versions upload - このヘルパーは対象IDを明示して100%へ指定し直し、deployment JSONをfail-closedで確認する
- フォールバックは「最新」ではなくデプロイ前後の一意差分を使い、0件・複数件なら停止する
- deployment 状態と本番HTTP レスポンスは別々に確認する
- sanitizerだけでlogの安全を保証しない
公式参考資料
