microCMSを更新したのに反映されない、が3回起きた話

はじめに

ポートフォリオサイトのCMSにmicroCMSを使っています。

先日、新しい作品をmicroCMSに登録したのに、サイトに何も出てこないということがありました。 登録は成功しています。APIを直接叩けば、ちゃんとデータも返ってきます。 それなのに、サイトを開いても作品が増えていない。

原因を追いかけていったら、「反映されない」が3回、それぞれ別の理由で起きていました。 どれも静的サイトとヘッドレスCMSを組み合わせると普通に踏むもので、しかも1回目以外は気づきにくいものでした。

今回はその記録です。

1つ目：ビルドしていなかった

まず最初の原因は、いま思えば当たり前のものでした。

このサイトはNext.jsの静的エクスポート（output: 'export'）で作っています。 つまり、CMSの中身はビルドしたときのHTMLに焼き込まれているということです。

microCMSに登録しても、それだけではHTMLは1文字も変わりません。 ビルドし直して、デプロイして、はじめて反映される。

頭では分かっていたつもりでしたが、CMSの管理画面で「公開」を押すと、なんとなくそれで終わった気になっていました。 実際、デプロイ済みのHTMLは作品を登録する前のもので、新しい作品のページ自体が存在していませんでした。

ビルドし直したら、あっさり出ました。

ここまでは、まあいいんです。問題は次でした。

2つ目：ビルドしたのに、sitemapだけ古い

ビルドし直して、作品ページも一覧も新しくなりました。

ところが、sitemap.xmlだけ新しい作品のURLが入っていません。 同じビルドで生成されているのに、そこだけ取り残されている。

原因は.next/cacheでした。

Next.jsはビルド時のfetch結果をキャッシュします。 microCMSのSDKも内部でfetchを使っているので、その対象になります。

作品ページのほうは新しいデータを取れていて、sitemapのほうは古いキャッシュを掴んでいた。 同じビルドの中で、新旧が混ざっていたわけです。

.next/cacheを消してからビルドし直したら、sitemapにもちゃんと入りました。

rm -rf .next/cache && npm run build

厄介なのは、ビルドは成功していて、エラーも警告も一切出ないことです。 出力されたファイルを1枚ずつ見にいかないと気づけません。

今はこれをnpmスクリプトに固定して、手で打つのをやめました。

"deploy": "rm -rf .next/cache && next build && wrangler deploy"

3つ目：記事を全部消したら、ビルドが落ちた

これは別の日の話です。

ブログを一度白紙にして書き直そうと思い、microCMSから記事を全部削除しました。 そのあとビルドしたら、こうなりました。

Error: Page "/blog/[slug]" is missing "generateStaticParams()"
       so it cannot be used with "output: export" config.

generateStaticParams()はちゃんと書いてあります。 ただ、記事が0件なので空の配列を返していた。

静的エクスポートでは、これが「関数が定義されていない」と同じ扱いになるようです。

つまり、コンテンツを空にすると、そのルートだけでなくサイト全体がビルドできなくなる。 新しい記事を1本書くまでデプロイが一切できない状態でした。

対処として、0件のときだけ存在しないslugを1つ返すようにしました。

export function withPlaceholder(slugs: string[]): { slug: string }[] {
  const params = slugs.map((slug) => ({ slug }));
  return params.length > 0 ? params : [{ slug: '__no-content' }];
}

詳細ページ側は該当データが見つからなければnotFound()に落ちるので、出力されるのは404ページが1枚だけ。 sitemapにも載りません。

同じ構造のルートが他にもあったので、まとめて同じ処理にしました。 作品を全部消しても、お知らせを全部消しても、もう落ちません。

おまけ：キャッシュにもう一度騙された

3つ目を直したあと、もう一度「反映されない」が起きました。

デプロイ直後に確認したときは新しい内容が出ていたのに、しばらくしてから見たら古い内容に戻っている。 ローカルのファイルは新しい。デプロイも成功している。それなのに古い。

これはCDNのエッジキャッシュでした。 レスポンスヘッダを見たらcf-cache-status: HIT。オリジンまで届いていませんでした。

このとき、自分の切り分けも一度間違えました。

ローカルのHTMLと配信中のHTMLをハッシュで比較して「全ページ不一致だ」と判断したのですが、 実際に差分を取ってみたら、違いはこれだけでした。

+ <script src="https://static.cloudflareinsights.com/beacon.min.js/...">

アクセス解析のビーコンが自動で注入されるので、ハッシュは必ず食い違います。 比較の方法そのものが間違っていました。

内容の一部をマーカーにして測り直したら、実際に古かったのは1ページだけでした。

まとめ

静的サイトとヘッドレスCMSを組み合わせると、CMSの「公開」ボタンから実際に人が見る画面までの間に、いくつも段があります。

• CMSに保存されたか
• ビルドがそれを取れたか（.next/cache）
• ビルド結果がデプロイされたか
• エッジキャッシュが古いものを返していないか

「反映されない」と思ったとき、どの段で止まっているかを先に切り分けたほうが早い、というのが今回の学びでした。 自分は毎回いちばん手前を疑って、毎回違う場所で止まっていました。

あと、キャッシュ関連はエラーが出ないのが一番厄介です。 ビルドは通るし、デプロイも成功する。それでも古いものが出ている。

だからこそ、手順のほうを固定してしまうのが結局は早いと思いました。 .next/cacheを消してからビルドする、というのをコマンドに埋め込んだのは、そういう理由です。