skills/microcms-guide/references/performance.md

# microCMS パフォーマンス・データ転送量最適化

最終確認: 2026-09-08

仕様の根拠は末尾の公式情報を参照する。設計上の推奨・コード例は本Skillの提案であり、唯一の公式推奨構成を意味しない。

## 目次

- [このリファレンスの役割](#このリファレンスの役割)
- [最初にボトルネックを分類する](#最初にボトルネックを分類する)
- [データ転送量の発生源を理解する](#データ転送量の発生源を理解する)
- [画像を最初に確認する](#画像を最初に確認する)
- [APIレスポンスを小さくする](#apiレスポンスを小さくする)
- [APIリクエスト回数を減らす](#apiリクエスト回数を減らす)
- [キャッシュを適切に利用する](#キャッシュを適切に利用する)
- [SSG・SSR・CSRと転送量](#ssgssrcsrと転送量)
- [調査フロー](#調査フロー)
- [避けたい最適化](#避けたい最適化)
- [429・5xxの切り分け](#4295xxの切り分け)

- [公式情報](#公式情報)

## このリファレンスの役割

microCMS利用時の表示速度、APIリクエスト量、データ転送量を改善する際の診断順序とベストプラクティスを提供する。

パフォーマンス問題に対して、いきなりフレームワーク変更や大規模なキャッシュ構成変更を提案しない。まず「何が大きいのか」「何回呼ばれているのか」「どこでキャッシュされているのか」を切り分ける。

## 最初にボトルネックを分類する

ユーザーが「遅い」「転送量が多い」と言っている場合、次を区別する。

1. **画像・ファイルの転送量が大きい**
2. **コンテンツAPIのJSONレスポンスが大きい**
3. **同じAPIを必要以上に何度も呼んでいる**
4. **ビルドやサーバーレンダリングで大量の取得が発生している**
5. **ブラウザ側でページ遷移・prefetchなどにより想定外の取得がある**
6. **microCMSではなく、フロントエンドやホスティング側がボトルネックになっている**

推測だけで原因を決めない。可能なら実際のリクエストURL、レスポンスサイズ、呼び出し回数、画像サイズ、レンダリング方式を確認する。

## データ転送量の発生源を理解する

microCMSのデータ転送量を考えるときは、大きく次を分ける。

- コンテンツAPIから返されるJSON
- microCMSで配信される画像・ファイルなどのメディア

多くのWebサイトでは、JSONより画像の方が1リクエストあたりのサイズが大きくなりやすい。転送量が増えている場合は、まず画像が占める割合を確認する。

また、レンダリング方式によってAPIアクセスが発生するタイミングが異なる。

- SSG: 主にビルド・再生成時にAPI取得が発生する。
- SSR: サーバーが必要に応じてAPI取得する。
- CSR: ブラウザからAPI取得するため、閲覧ごとに取得が発生しやすい。

ただし、実際の回数はフレームワークのキャッシュ、CDN、prefetch、再検証、ホスティング構成によって変わる。フレームワーク固有の挙動は対応する専門Skillで確認する。

## 画像を最初に確認する

画像転送量が大きい場合は、`image-api.md` を読み、次の順序で見直す。

1. 表示領域より大きすぎる画像を配信していないか。
2. `w` / `h` を利用して必要な寸法へ縮小できないか。
3. WebP / AVIFなど適切な形式を利用できないか。
4. `q` で品質を調整できないか。
5. `srcset` / `sizes` 等で画面幅に応じた画像を配信できないか。
6. 画面外画像を必要以上に先読みしていないか。

「品質を下げる」より、まず不要なピクセルを送らないことを優先する。

## APIレスポンスを小さくする

### `fields` を使う

一覧画面で本文・大きな参照データなどが不要なら、必要なフィールドだけ取得する。

例:

```text
fields=id,title,eyecatch,publishedAt
```

一覧で本文全文を取得し、表示せず捨てるような実装は避ける。

### `depth` を必要最低限にする

参照コンテンツを使っている場合、必要以上に深い `depth` を指定するとレスポンスが大きくなる。

- 参照先IDだけでよい → `depth=0` を検討
- 1階層の情報だけ必要 → デフォルトまたは必要な深さだけ指定

### 一覧取得件数を適切にする

リスト形式の一覧取得では `limit` を用途に合わせる。

「後で使うかもしれない」ために全コンテンツを毎回取得しない。

UIが10件ずつ表示するなら、ページネーションや必要件数のみの取得を検討する。

## APIリクエスト回数を減らす

同じページで同一URL・同一条件のAPIリクエストが複数回発生していないか確認する。

代表的な原因:

- 複数コンポーネントがそれぞれ同じ一覧APIを取得している。
- 一覧取得後に、各コンテンツの詳細APIをN回追加で取得している。
- 参照で取得できる情報を、別リクエストでも取り直している。
- サイトマップや静的生成で全件取得を何度も繰り返している。
- ブラウザのprefetchによって、閲覧していないページのデータまで取得されている。

必要な情報が一覧API + `fields` / `depth` でまとめて取得できるなら、N+1リクエストを避ける。

一方、レスポンスが巨大になるなら分割した方がよい場合もある。リクエスト回数だけをKPIにしない。

## キャッシュを適切に利用する

microCMSのGET APIはCDNを経由して配信される。ただし、アプリケーション側にもNext.js、ブラウザ、ホスティングCDNなど複数のキャッシュ層が存在しうる。

更新が反映されない問題では「microCMSのCDNが原因」と決めつけず、次の層を分けて確認する。

```text
microCMS Content API / CDN
        ↓
アプリケーションのデータキャッシュ
        ↓
ページ / HTMLキャッシュ
        ↓
ホスティングCDN
        ↓
ブラウザ
```

Content APIのCDNキャッシュはURLだけでなく、APIキー・リクエスト元の地域・一部のヘッダー・更新状態・有効期限などにも依存する。`x-cache` の `Hit from cloudfront` / `Miss from cloudfront` を確認し、同じURLだから必ずヒットするとは判断しない。[公式ヘルプ：GETのキャッシュ条件](https://help.microcms.io/ja/knowledge/how-to-use-content-api-caching)

キャッシュは「長ければよい」のではなく、要求される更新反映時間とのバランスで決める。

- 即時性が低い → 長めのキャッシュが適する。
- コンテンツ公開時にすぐ反映したい → Webhook + On-demand Revalidation等を検討する。
- 常に最新が必要 → 動的取得を検討する。

Next.js固有のキャッシュ設計は `microcms-nextjs` を使用する。

## SSG・SSR・CSRと転送量

### SSG

コンテンツAPI取得は主にビルドや再生成時に発生するため、ページ閲覧数とAPIリクエスト数が直接比例しにくい。

ただし、ビルドのたびに大量コンテンツを全件取得している場合は、ビルド回数と取得量を確認する。

### SSR

サーバー側で取得する。アプリケーション側キャッシュがなければアクセス量に応じてAPI呼び出しが増える可能性がある。

### CSR

ブラウザからコンテンツAPIへ直接アクセスする。ページ閲覧・コンポーネントマウント・クライアント側再取得などがリクエスト量へ直結しやすい。

### 画像・ファイル

画像やファイルはレンダリング方式に関係なく、最終的にブラウザまたは画像最適化サービスからリクエストされる。APIデータの取得方式だけを変えても、画像転送量問題が解決するとは限らない。

## 調査フロー

「データ転送量が急増した」という相談では、次の順に確認する。

### 1. いつから増えたか

- リリース日
- キャンペーンやPV増加
- 画像差し替え
- フレームワークやホスティング変更
- prefetchやクローラー挙動の変更

### 2. JSONかメディアか

どちらが大きいかを先に分ける。

### 3. メディアなら

- 元画像サイズ
- 実表示サイズ
- 画像APIパラメータ
- レスポンシブ配信
- 同じ画像の重複読み込み

を確認する。

### 4. APIなら

- 呼び出しURL
- `limit`
- `fields`
- `depth`
- 呼び出し回数
- 全件取得の有無
- N+1

を確認する。

### 5. レンダリング・キャッシュを確認する

- SSG / ISR / SSR / CSR
- アプリケーションキャッシュ
- Webhook / 再検証
- prefetch

を確認する。

### 6. 小さい変更から適用する

例:

1. 画像を縮小する。
2. `fields` を絞る。
3. 重複取得を除く。
4. キャッシュを調整する。
5. それでも必要ならレンダリング方式・アーキテクチャを見直す。

## 避けたい最適化

- 転送量の内訳を見ずにSSRからSSGへ全面移行する。
- 画像が主因なのにJSONの数KB削減だけに集中する。
- 表示幅300pxの画像へ2000px以上の元画像を常時配信する。
- 一覧ページで本文や不要な参照データまで取得する。
- 毎ページで `getAllContents` 相当の全件取得をする。
- 更新要件を無視してキャッシュ時間だけを極端に長くする。
- フレームワークのキャッシュとmicroCMSのCDNを同じものとして説明する。

最適化案を出すときは、「何を削減する施策か」「どの層へ効くか」「更新反映への影響」をセットで説明する。

## 429・5xxの切り分け

429では、CDNで処理された総アクセスとオリジンへのリクエストを分ける。公式ヘルプで説明される呼び出し制限はオリジンへのアクセスが対象。上限値は対象APIの最新制限を確認し、同時実行数・間隔・複数ワーカーの合計リクエストを抑える。リトライ回数を増やすだけで解決しようとしない。[公式ヘルプ：429への対処](https://help.microcms.io/ja/knowledge/handling-429-errors)

5xxが散発する場合は待機を挟む再試行を検討し、頻発する場合は並列数・`depth`・取得件数・複雑なAND/OR条件を見直す。一部の絞り込みを取得後へ移す選択肢もあるが、取得量やページネーションの意味が変わらないか検証する。[公式ヘルプ：500番台への対処](https://help.microcms.io/ja/knowledge/api-500-errors)

## 公式情報

- [データ転送量](https://document.microcms.io/manual/data-amount)
- [データ転送量を節約する方法](https://help.microcms.io/ja/knowledge/reduce-data-costs)
- [コンテンツAPIの取得条件・レスポンス制限](https://document.microcms.io/content-api/get-list-contents)