Web ビルドのブラウザーキャッシュ

Flutter の Web ビルドはただのファイルで、ブラウザーがそれをどれだけ保持するかは、静的ホストがヘッダーのファイルで伝えます。spring.web.resources.cache.cachecontrol.* のキーを設定すると、build_runner はビルドのたびにキャッシュの規則をアプリの web/_headers (Cloudflare Pages のヘッダーのファイル) に書き込みます。ビルドのファイルは開くたびに問い合わせ直され、アプリの画像やフォントはキーのとおりに保持されます。キーは Spring Boot のもので、サーバーの静的リソースの Cache-Control を決めるものと同じです。

使う理由

Flutter の Web ビルドは、ファイル名にハッシュを付けません。index.html、main.dart.js、main.dart.wasm、flutter_bootstrap.js、アセットのマニフェストです。ブラウザーがこれらを保持すると、デプロイの後も古いビルドを動かしてしまうので、no-cache が必要です。一方、/assets/ の下にあるアプリ自身の画像やフォントはめったに変わらず、何日も保持してかまいません。手で書いたヘッダーのファイルは、たいていどちらかを誤ります。すべてのパスを no-cache にすると開くたびにすべての画像をダウンロードし直し、すべてのパスに長い max-age を付けると古いビルドが残ります。

例

# lib/resources/application-web.yml
spring:
  web:
    resources:
      cache:
        cachecontrol:
          max-age: 30d
          cache-public: true

dart run build_runner build の後、web/_headers には次のブロックがあります:

# spring:cache:start
# Generated from spring.web.resources.cache.cachecontrol.* on every build: change the configuration, not these lines.
/*
  ! Cache-Control
  Cache-Control: no-cache
/assets/*
  ! Cache-Control
  Cache-Control: max-age=2592000, public
/assets/AssetManifest*
  ! Cache-Control
  Cache-Control: no-cache
/assets/FontManifest.json
  ! Cache-Control
  Cache-Control: no-cache
/assets/NOTICES
  ! Cache-Control
  Cache-Control: no-cache
/assets/*/manifest.json
  ! Cache-Control
  Cache-Control: no-cache
/assets/shaders/*
  ! Cache-Control
  Cache-Control: no-cache
/assets/fonts/MaterialIcons-Regular.otf
  ! Cache-Control
  Cache-Control: no-cache
/assets/packages/cupertino_icons/*
  ! Cache-Control
  Cache-Control: no-cache
/assets/lib/resources/*
  ! Cache-Control
  Cache-Control: no-cache
# spring:cache:end

flutter build web は web/ を build/web/ にコピーするので、このファイルはデプロイするもののルート、つまりホストが読む場所に置かれます。

どのパスに何が付くか

パス Cache-Control 理由
/*: ページ、main.dart.js、main.dart.wasm、flutter_bootstrap.js、manifest.json など /assets/ の外のすべて no-cache どのビルドでも名前が同じ。ブラウザーは毎回問い合わせ、変わっていなければ本文のない 304 を受け取るので、デプロイはすぐに反映される
/assets/*: アプリの画像、フォント、その他のアセット キーから作った値 めったに変わらない
/assets/AssetManifest*、/assets/FontManifest.json、/assets/NOTICES、/assets/*/manifest.json no-cache アセットとフォントのマニフェスト、ライセンス、flutter_scene のシェーダーのマニフェストはビルドのたびに変わる
/assets/shaders/* no-cache エンジンのシェーダー。アプリと一緒にビルドされる
/assets/fonts/MaterialIcons-Regular.otf、/assets/packages/cupertino_icons/* no-cache Flutter はアイコンフォントを、アプリが使うアイコンだけに削って毎回同じ名前で出力する。古いものが残っていると、新しいアイコンが四角で表示される
/assets/lib/resources/* no-cache コードに埋め込まず実行時に読むアプリのリソース: Markdown のページ、メッセージ、検索インデックス。ハッシュがなく内容とともに変わるので、残っていると、デプロイ前のページが表示される

規則の組み合わさり方

ホストは、パスが一致するすべての規則をファイルの順に適用します。ブロックの各規則は ! Cache-Control で始まります。これは前の規則が付けた Cache-Control を外す Cloudflare の書き方で、そのためパスには、一致する最後の規則の値が付きます:

# The app's own rules.
/*
  X-Frame-Options: DENY

# spring:cache:start
...
# spring:cache:end

/fonts/*
  ! Cache-Control
  Cache-Control: max-age=31536000, immutable

ファイルの中のブロック

キー

/assets/* の値は、Spring Boot がサーバーのヘッダーを作るのと同じように作られます。no-store があればそれ、なければ no-cache、なければ max-age で始まり、続いて must-revalidate、no-transform、public、private、proxy-revalidate、s-maxage、stale-if-error、stale-while-revalidate の順です。

キー 型 ディレクティブ
spring.web.resources.cache.cachecontrol.max-age 期間 max-age=<秒>
spring.web.resources.cache.cachecontrol.no-cache bool no-cache。max-age より優先
spring.web.resources.cache.cachecontrol.no-store bool no-store。no-cache と max-age より優先
spring.web.resources.cache.cachecontrol.must-revalidate / no-transform / proxy-revalidate bool 同じ名前のディレクティブ
spring.web.resources.cache.cachecontrol.cache-public / cache-private bool public / private
spring.web.resources.cache.cachecontrol.s-max-age 期間 s-maxage=<秒>
spring.web.resources.cache.cachecontrol.stale-while-revalidate / stale-if-error 期間 同じ名前のディレクティブ (秒)

Spring Boot がこれらのキーを読むのと同じく、単位のない期間は秒です (3600)。30d、2h、PT1H も書け、ヘッダーには整数の秒が入ります。spring.web.resources.cache.period と use-last-modified はここでは読まれません。ブロックを作るのは cachecontrol.* のキーだけです。

ホスト

このブロックは Cloudflare Pages 向けです。前の規則のヘッダーを外す ! Cache-Control は Cloudflare の書き方です。Netlify も _headers を読みますが、この行は解釈しません。Netlify や、_headers を読まないホスト (GitHub Pages、Firebase Hosting) では、同じ規則をホストの設定に書いてください。spring_boot_starter_web でビルドを配信する Dart のサーバーは、同じキーから Cache-Control を自分で送り、その値はすべてのファイルで同じです。静的リソース を参照してください。

独自ドメインのサイトは、ゾーンのキャッシュ設定の後ろにあり、その設定がファイルより後に効きます。Caching → Configuration → Browser Cache TTL が時間 (古いゾーンの既定は 4 時間) になっていると、Cloudflare は静的とみなすファイル (スクリプト、画像、フォント) の no-cache をその時間に置き換えます。すると flutter_bootstrap.js、main.dart.js (Chromium 以外のすべてのブラウザが動かすビルドで、Flutter の既定です。Safari、Firefox、iOS のすべてのブラウザ) とアイコンフォントがデプロイ後もその時間まで保持され、スマートフォンには前のビルドが表示されます。Browser Cache TTL を Respect Existing Headers にする (または Cache Rule のブラウザ TTL をオリジンに従わせる) と、ファイルが決めるようになります。そのとき curl -sI https://<site>/main.dart.js は cache-control: no-cache を返します。

Spring (Java) との対応

Spring に対応するものはありません。Spring Boot のサーバーはヘッダーを自分で送ります。ここでは同じキーが、Spring のコードを動かさない静的ホストにまで届きます。

関連項目