起きたこと: deploy結果を「成功表示」で終わらせない
2026年7月24日にCloudflare公式資料とこのブログのdeploy helperを照合しました。
公式仕様では、wrangler deployは新しいWorker versionを作り、通常はそのまま100% trafficへdeployします。
routesを外した設定を渡しても、upload-onlyのwrangler versions uploadへ変わるわけではありません。
このブログでは、既存custom domain routeを変更できない限定tokenでroutine deployするため、build後の設定からroutesだけを外します。
そのうえでhelperは、wrangler deployが返したversion IDを特定し、同じIDをwrangler versions deployで100%へ明示し直し、wrangler deployments list --jsonで確認します。
これはproject固有の保守的な手順であり、一般のwrangler deployがuploadだけで終わるという主張ではありません。
Worker deploy、version ID特定、100% traffic確認、別工程のHTTP確認を分離した手順*図: Worker deploymentの確認と、本番custom domainのHTTP確認は別の証拠です。このhelperが自動確認するのはdeployment JSONまでで、live HTTP確認は後続工程です。*
このhelperの実行順
実コードは--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を確認
この引数は、projectで使うWrangler 4.94.0のCLI helpとも一致します。
本当にuploadとdeployを分離したい場合の公式commandはwrangler versions uploadです。
Cloudflare公式資料では、route・domain・cron triggerの変更は別にwrangler triggers deployを使うよう案内されています。
Version ID fallback: 「最新」ではなく一意差分
wrangler deployのhuman-readable出力にCurrent Version ID: <uuid>があれば、厳格なUUID patternで取得します。
ただし、表示形式が変わった場合にdeploy後の「最新version」を採用してはいけません。
同時に別のuploadが走ると、無関係なversionを100%へpromoteする危険があるためです。
helperはdeploy前のwrangler versions list --jsonを保存し、必要な場合だけdeploy後にも取得します。
前後集合の一意差分が、妥当なUUID 1件だけなら採用します。
差分が0件または複数ならversionを推測せず失敗します。
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の終了codeだけでは完了にしません。
wrangler deployments list --jsonを読み、時刻順で最新のdeploymentに対象versionが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 stateです。
custom domainで新しいHTMLやassetが返ることまでは証明しないため、deploy後に本番URLを別途HTTP・browserで確認します。
Log sanitizerは補助線
helperはstdoutとstderrをそのまま転送せず、email、account ID、既知の公開識別子、環境変数値などをpatternで置換します。
しかしpattern-based sanitizerは未知のcredentialや新しい出力形式まで安全を保証しません。
secretをlogへ出さない設計、CI側のmask、staged secret scanを前提にし、その上で偶発的な露出を減らす補助として使います。
まとめ
wrangler deployは通常、version作成と100% deployを一度に行う- upload-onlyの公式commandは
wrangler versions upload - このhelperは対象IDを明示して100%へ指定し直し、deployment JSONをfail-closedで確認する
- fallbackは「最新」ではなくdeploy前後の一意差分を使い、0件・複数件なら停止する
- deployment stateと本番HTTP responseは別々に確認する
- sanitizerだけでlogの安全を保証しない
公式参考資料
