skills/microcms-guide/references/preview.md

# microCMS プレビュー

最終確認: 2026-09-08

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

## 目次

- [このリファレンスの役割](#このリファレンスの役割)
- [プレビューの基本構造](#プレビューの基本構造)
- [画面プレビューURLを設定する](#画面プレビューurlを設定する)
- [Draft Keyを使って下書きを取得する](#draft-keyを使って下書きを取得する)
- [プレビュー用エンドポイントを設ける](#プレビュー用エンドポイントを設ける)
- [セキュリティ](#セキュリティ)
- [複数コンテンツ・参照コンテンツのプレビュー](#複数コンテンツ参照コンテンツのプレビュー)
- [公開サイトとプレビューを分ける判断](#公開サイトとプレビューを分ける判断)
- [トラブルシューティング](#トラブルシューティング)
- [フレームワーク固有Skillへ委ねる範囲](#フレームワーク固有skillへ委ねる範囲)
- [公式情報](#公式情報)

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

microCMSの画面プレビューとDraft Keyを使った、フレームワークに依存しないプレビュー設計を説明する。

microCMSはヘッドレスCMSのため、管理画面だけでWebサイトのプレビュー表示が完成するわけではない。フロントエンド側に「下書きデータを取得してレンダリングする仕組み」が必要になる。

## プレビューの基本構造

基本的な流れは次の通り。

```text
microCMS管理画面
  ↓ 画面プレビューボタン
プレビュー用URL
  ├─ CONTENT_ID
  └─ DRAFT_KEY
  ↓
フロントエンド
  ↓ draftKeyを付けてContent APIを取得
microCMSの下書きコンテンツ
  ↓
プレビュー表示
```

公開中のコンテンツを通常取得する処理と、下書きを取得する処理を意図せず混在させない。

## 画面プレビューURLを設定する

API設定の画面プレビューでは、遷移先URLへ動的な値を埋め込める。

代表的な形式:

```text
https://example.com/api/preview?contentId={CONTENT_ID}&draftKey={DRAFT_KEY}
```

または、フレームワークや構成によっては直接プレビューページへ遷移してもよい。

```text
https://example.com/preview/{CONTENT_ID}?draftKey={DRAFT_KEY}
```

`{CONTENT_ID}` と `{DRAFT_KEY}` は、microCMS管理画面からプレビュー対象の値へ置き換えられる。

各プレースホルダーはURL内で1個だけ使用する前提で設計する。

## Draft Keyを使って下書きを取得する

下書き状態のコンテンツを取得するには、コンテンツAPIへ `draftKey` クエリを付ける。

概念例:

```text
GET /api/v1/articles/{CONTENT_ID}?draftKey={DRAFT_KEY}
```

`microcms-js-sdk` では `queries` に渡す。

```ts
const article = await client.getListDetail({
  endpoint: 'articles',
  contentId,
  queries: {
    draftKey,
  },
})
```

Draft Keyで通常取得する下書きコンテンツは、プレビュー対象となる1コンテンツを前提に考える。

複数の下書きコンテンツをまとめて取得する必要がある場合は、APIキーの「下書き全取得」権限が関係する。単一記事のプレビューのためだけに、安易に強い権限を付与しない。

## プレビュー用エンドポイントを設ける

本番サイトでプレビューを実装する場合、管理画面からDraft Keyを直接ページコンポーネントへ渡すだけでなく、プレビュー開始用のエンドポイントを設ける構成が扱いやすいことが多い。

そのエンドポイントでは次を行う。

1. 受け取ったリクエストが正当なプレビュー要求か検証する。
2. `contentId` と `draftKey` が存在するか確認する。
3. 必要ならmicroCMSへ問い合わせ、対象コンテンツを取得できるか検証する。
4. フレームワーク側のプレビューモードを有効化する。
5. 対象ページへリダイレクトする。

この「プレビュー開始エンドポイント」はフレームワークによって実装が異なる。Next.jsではDraft Modeを使う構成を `microcms-nextjs` で扱う。

## セキュリティ

Draft Keyは下書きコンテンツ取得に使う値なので、不必要に公開・保存しない。

### 推奨事項

- Draft Keyをソースコードへハードコードしない。
- Draft Keyをログ、分析ツール、外部サービスへ不用意に送らない。
- プレビュー開始URLに独自のシークレットを追加し、第三者が任意にプレビューモードを有効化できないようにすることを検討する。
- APIキーはサーバー側へ置き、必要最低限の権限にする。
- プレビュー用エンドポイントから任意URLへリダイレクトできる実装にしない。
- `contentId` やリダイレクト先は、想定するAPI・パスの範囲で検証する。

URLクエリにDraft Keyを含める構成では、アクセスログ、Referer、外部計測などへ値が流れる可能性も考慮する。

フレームワークにプレビューセッションを保持する仕組みがある場合、開始時だけDraft Keyを受け取り、その後はサーバー側で扱う設計を優先する。

## 複数コンテンツ・参照コンテンツのプレビュー

記事本体のDraft Keyを使って記事を取得しても、参照先の別コンテンツが下書きの場合、その下書きまで常に同じ条件で取得できるとは限らない。

プレビュー要件を決めるときは次を確認する。

- プレビュー対象は記事本体だけでよいか。
- 参照している著者・カテゴリ・関連コンテンツの下書きも同時に見たいか。
- サイト全体を「下書き状態込み」で確認する必要があるか。

複数の下書きをまとめて取得するために強いAPIキー権限が必要になる場合は、そのキーを必ずサーバー側で管理し、公開サイト用キーと分けることも検討する。

「プレビューだからすべての下書きを取得可能にする」をデフォルトにしない。

### 下書きの値で検索しても見つからない

「公開中かつ下書き中」のコンテンツは、下書き全取得権限があっても検索条件の判定には公開中の値が使われる。返却内容は下書きの値になり得るため、検索対象と返却値を区別する。プレビュー対象が分かる場合は、変更中のslug等で一覧検索するよりIDとDraft Keyで詳細取得する。[公式ヘルプ：公開中かつ下書き中の検索](https://help.microcms.io/ja/knowledge/public-and-draft-content-filtering)

下書き記事の画像・添付ファイルも、標準メディアへアップロードした時点で公開される。Draft ModeやDraft KeyはメディアURLの閲覧制限にならない。[公式ヘルプ：メディアの閲覧制限](https://help.microcms.io/ja/knowledge/file-view-restrictions)

## 公開サイトとプレビューを分ける判断

### 同じフロントエンドでプレビューする

向いているケース:

- 公開サイトと同じUIを正確に確認したい。
- フレームワークにDraft Mode等のプレビュー機能がある。
- プレビュー時だけ動的取得へ切り替えられる。

### プレビュー専用環境を用意する

向いているケース:

- 本番サイトへプレビュー用ロジックを持ち込みたくない。
- ステージング環境がすでにある。
- 本番とは異なるアクセス制御が必要。

ただし、環境を分けるほど設定差分やデプロイ運用が増える。必要性が明確な場合だけ採用する。

## トラブルシューティング

### 公開内容しか表示されない

確認する順序:

1. プレビューURLに `contentId` と `draftKey` が渡っているか。
2. フロントエンドが `draftKey` をAPIリクエストへ渡しているか。
3. 公開用データがキャッシュされていないか。
4. プレビューモードが有効になっているか。
5. 対象API・コンテンツIDが正しいか。

### プレビューだけ404になる

- 公開コンテンツだけを対象にした静的パス生成になっていないか。
- 下書きコンテンツIDのルートを動的に処理できるか。
- Draft Key付きの詳細取得を実行しているか。

### 変更がプレビューへ反映されない

公開サイトのキャッシュとは別に、プレビュー時の取得もキャッシュしていないか確認する。

プレビューは通常、編集直後の状態確認が目的なので、公開サイトと同じ長時間キャッシュをそのまま適用しない。

## フレームワーク固有Skillへ委ねる範囲

このリファレンスでは、microCMS側の画面プレビュー・Draft Key・セキュリティ上の原則まで扱う。

以下は専門Skillへ委ねる。

- Next.js Draft Mode
- `draftMode()`
- Route Handler
- Next.jsのプレビュー中のキャッシュ挙動
- プレビュー開始・終了用ルート
- Next.jsのDynamic Routesとの組み合わせ

Next.jsの場合は `microcms-nextjs` を使用する。

## 公式情報

- [画面プレビュー](https://document.microcms.io/manual/screen-preview)
- [draftKeyと一覧取得](https://document.microcms.io/content-api/get-list-contents)
- [APIキーと下書き全取得権限](https://document.microcms.io/content-api/x-microcms-api-key)