ファイル命名とキャッシュバスティング完全ガイド（fingerprint / version / 参照更新）

画像やOGPを差し替えても、ユーザー側キャッシュに阻まれると反映されません。最短の解はファイル名にバージョン（v2/v3）やハッシュを埋め込むこと。ここでは命名規則と参照更新、配信までを運用可能な型に落とし込みます。

要点（TL;DR）

命名は {name}-{width}w-v{version}.{ext} か {name}.{hash}.{ext} を採用。
参照は全置換（検索ヒット0件を確認）。
配信はimmutable（ハッシュ）orSWR（差し替え多）で統一。
公開前に /compare と CWV を確認。

1. 命名パターン（選び方）

# 幅ベース＋バージョン
hero-1200w-v2.webp
thumb-640w-v5.webp

# ハッシュ（ビルドパイプライン前提）
hero.1c9a6f.webp
thumb.7a2b3d.webp

手運用なら v2/v3 が安定。ビルドに組み込めるならハッシュが最強です。どちらも /rename のプリセットに保存しておくと運用がぶれません。

2. 参照更新の最短手順（安全な置換）

# VS Code 正規表現例
src=\x22(.*?)-(\d+)w-v(\d+)\.(webp|jpg|png)\x22
→ src="$1-$2w-v3.$4"

# PowerShell 一括置換（例）
Get-ChildItem -Recurse -File -Include *.md,*.html |
  ForEach-Object {
    (Get-Content $_ -Raw) -replace '-v\d+\.', '-v3.' | Set-Content $_
  }

置換後はリンク切れ0件を確認し、/compare で見えの回帰がないかをチェックします。

3. 配信の設計（immutable / SWR）

ハッシュ運用 → Cache-Control: public, max-age=31536000, immutable
差し替え多 → public, max-age=300, stale-while-revalidate=86400

詳細はキャッシュ制御ガイドを参照。

4. 公開前チェック（10項目）

命名規則が決まり、/rename に保存済み。
参照は全置換（検索結果=0）。
OGP/メール向けの派生も命名を踏襲。
配信方針（immutable / SWR）が統一。
CLSゼロ（寸法明示、広告は固定高）。
Before/After を /compare で確認。
GA4 イベント（zip_download等）が計測。
サイトマップに新URL反映。
Search Console にエラー無し。
機微情報をファイル名に含めていない。

5. まとめ：名前でキャッシュを制す

指紋（v2/ハッシュ）と参照更新のセットをルール化すれば、差し替え運用は安定します。まずは /rename をワークフローに組み込みましょう。