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

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

## 使う理由

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

## 例

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

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

```text
# 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` のキーはない。

```text
# 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` を自分で送り、その値はすべてのファイルで同じです。[静的リソース](../spring-boot-starter-web/static-resources.md) を参照してください。

独自ドメインのサイトは、ゾーンのキャッシュ設定の後ろにあり、その設定がファイルより後に効きます。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 のコードを動かさない静的ホストにまで届きます。

## 関連項目

- [Web](web.md)
- [静的リソース](../spring-boot-starter-web/static-resources.md)
- [ネットワーク上のリソース](resources.md)
- [ビルドが読むプロパティ](../spring-core-dart-generator/build-properties.md)
- [すべてのプロパティ](properties.md)
