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 の書き方で、そのためパスには、一致する最後の規則の値が付きます:
/assets/logo.pngは/*と/assets/*に一致する:max-age=2592000, public。/assets/AssetManifest.bin.jsonは/*、/assets/*、/assets/AssetManifest*に一致する:no-cache。- ブロックより前にあるアプリの規則に対しては、ブロックが優先される。ブロックの
/*がそれらのCache-Controlを外す。それらの規則のほかのヘッダー (X-Frame-Options、Content-Security-Policy) は残る。 - ブロックより後にあるアプリの規則は、ブロックより優先される。内容に応じて名前が変わるファイルに
immutableを付けるなら、ここに書く。サーバーと同じく、immutableのキーはない。
# The app's own rules.
/*
X-Frame-Options: DENY
# spring:cache:start
...
# spring:cache:end
/fonts/*
! Cache-Control
Cache-Control: max-age=31536000, immutable
ファイルの中のブロック
- 書き込むもの。 ジェネレーターのページローダーのビルダーです。
spring_boot_starter_flutterに依存し、web/index.htmlを持つアプリで動きます。設定は、アプリがブラウザーで読むのと同じように読みます。application.*、次にapplication-web.*、そしてそこでspring.profiles.activeが指定するプロファイルのファイルです。--dart-defineの値は数えません。 - マーカー。 ブロックは
# spring:cache:startから# spring:cache:endまでで、最初の行がその出どころを示します。ビルドのたびに書き直されるので、変えるのはその行ではなく設定です。 - 置き場所。 マーカーのある場所です。初回はアプリの規則の後に、空行を 1 行はさんで置かれます。ファイルがなければ作られます。2 つ目のブロックは取り除かれます。
- 残りはアプリのもの。 ブロックの前後の規則はそのまま残ります。
- キーがなくなれば、ブロックもなくなる。 キーが一つも設定されていなければ (または
falseだけなら)、ブロックは取り除かれ、ほかに何もなければファイルも消えます。 - 誤った値 (
max-age: 30 days、cache-public: maybe) は、キーを示してビルドを失敗させ、ファイルはそのまま残ります。
キー
/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 のコードを動かさない静的ホストにまで届きます。