Q.Studioから移ったmicroCMSで、プレビュー・画像最適化・更新が反映されない時の設定はどうしますか？

公開前の記事を確認するには、まず対象APIの「API設定」から「画面プレビュー」を開きます。「遷移先URL」に表示用ページのURLを入れ、「変更する」を押してください。これでコンテンツ詳細画面に画面プレビューのボタンが出て、そこから登録したURLへ移れるようになります（画面プレビューの設定手順）。

ただ、URLを登録しただけでは下書きは表示されません。表示側のページで、URLに付いたコンテンツIDとdraftKeyを受け取り、その値でmicroCMSから下書きのデータを取ってきて描画する処理を書いておきます。遷移先URLには{CONTENT_ID}と{DRAFT_KEY}を埋め込みますが、どちらもURLの中で使えるのは1個ずつです。2個目以降は実際の値に置き換わりません。

Astroの静的サイトの場合、プレビュー用のページをサーバーで動かすことが前提になるわけではありません。ブラウザー側のJavaScriptで下書きを取りに行く形でも組めます。この方法では閲覧者にAPIキーが知られ得るので、キーの権限はGETのみにするなど絞っておきます（Astroでのプレビュー実装）。サーバー側で生成したいときは、実行環境に合うアダプターを入れ、そのページの先頭にexport const prerender = falseを書きます。ほかのページは静的生成のまま残ります。

Studioでは画像の配信をほぼ任せきりでしたが、microCMSでは画像URLの後ろにパラメータを付けて、加工した画像を受け取ります。画像処理にはimgixのRendering APIが使われていて、サイズの変更、切り抜き、圧縮ができます。よく使う指定は次のとおりです。

一方で、できないこともあります。次世代フォーマットへ自動変換する「?auto=format」には対応していません。また、SVG形式の画像や、Amazon S3連携を有効にした環境では画像API自体が使えません（画像APIの対応範囲）。パラメータを何も付けなければ元の画像がそのまま配信されるので、移行後にページが重いと感じたら、まず画像URLにwやqが付いているかを見るのが早いですね。

リッチエディタの画面内で個別に直接設定できるパラメータもwとhだけに絞られているため、細かい圧縮や切り抜きをサイト全体で行うなら、フロントエンド側でHTMLを解析してURLを書き換える実装を挟みます。

管理画面で記事を更新して保存したのに、本番サイトの表示が古いまま変わらないのは何が原因でしょうか。Studioの場合でもデザイン編集後は公開パネルからサイト更新を手動で行う仕組みでしたが、microCMSでは「CMS側のデータ保存」と「公開サイトのHTML生成」が完全に切り離されている点が大きな違いです。

静的サイトとして生成している環境では、記事を書き換えただけでは本番のHTMLは作り直されません。記事の変更を検知してWebサイト側を自動で再構築するには、Webhookの連携が必要です。microCMSの各API設定にある「Webhook」を開くと、Cloudflare PagesやVercel、Netlify、GitHub Actionsなどの通知先が選べます。Cloudflare PagesならDeploy Hooksと組み合わせることで、記事を変えるたびに新しいビルドが自動で配信されます。

もう一つの見落としがちな要因が、配信フレームワーク側のキャッシュ保持です。例えばNext.js 15を採用しているサイトでは、Data Cacheと呼ばれる取得データの保存機能が働き、単にサイトを再デプロイしただけではキャッシュが引き継がれて内容が更新されないケースがあります。取得データまで新しくしたいなら再検証を入れるか、キャッシュを使わない設定にしてください（Next.js 15のキャッシュ）。

手動での即時公開なら反映されるのに、日時を指定した予約公開だけサイトに表示されないという状況はよく起こります。まず、Webhookの通知タイミングを開いてください。予約による新規公開や更新は「コンテンツの公開（予約設定による操作）」という別の項目に分かれています。「コンテンツの公開（予約設定による操作）」にチェックが入っていないと、指定時刻を迎えて管理画面側が公開状態に切り替わっても、再ビルドを促す通知が配信基盤へ一切送られません。

Cloudflare Pagesなら、デプロイログのSource欄でDeploy Hookから動いたビルドを見分けられます。数分後に公開される試しの記事を予約し、その時刻にDeploy Hook由来のビルドが記録されるか見てみると、原因の切り分けが進みますね。

通知そのものが届いていないこともあります。Webhookを無効にしていれば通知は出ません。また、通知が送信されたとしても、ネットワークの不具合や相手先サーバーの4xx・5xxエラーで失敗した場合、microCMS側からの自動再送は行われない仕様です。さらに、ビルド自体は完了していても、サイトのページ数や静的ファイルの配信ラグによって数分程度の待ち時間が生じることもあります。

Next.jsのApp Routerでは、再ビルドしてもAPI応答のキャッシュが残り、データが古いままのことがあります。この場合はビルド前にフェッチキャッシュを消すと直ることがあり、コンテナ環境のビルドなら基本的にキャッシュファイルは消えているので特別な対応は要りません（App Routerのキャッシュ）。心当たりがなければ数分待ち、それでも出ないときは対象記事のURLをサイト管理者に伝えて見てもらいましょう。

「API連携と聞くと難しそう」「生のfetch関数でURLやヘッダーを細かく書くのは面倒」と感じる人もいるのではないでしょうか。実際に書くのは、最初の接続部分と取得の呼び出しが中心です。導入時は「npm install microcms-js-sdk」を実行し、コード内でcreateClient関数を呼び出してクライアントを初期化します。設定に必要なのはserviceDomainとapiKeyの2つです。serviceDomainには「xxxx.microcms.io」の全体ではなく、サブドメインにあたる「xxxx」の部分だけを指定します。Astroなどで開発する場合は、プロジェクト直下の.envファイルにこれらの値を記述し、環境変数経由で読み込ませるのが標準的な手順です。

取得には、APIの形に合わせてメソッドを使い分けます。

• getList：リスト形式APIの一覧を取る
• getListDetail：IDを指定して1件を取る
• getObject：オブジェクト形式APIを取る

以前使われていた汎用の「get」メソッドは非推奨となっているため選ばないようにしましょう。下書き記事を取り出したいときは、getListDetailの引数にendpointとcontentIdを渡し、queriesの中にdraftKeyを文字列で添えれば取得できます。ここまでは下書きのデータを取る部分なので、プレビュー画面に表示する処理は別に組みます。

ただ、.envに置けばブラウザーから見えなくなる、というわけではありません。