Hugo + Cloudflare Pagesでブログを構築する過程で、同じような問題に何度も引っかかった。どれもHugo特有の挙動で、知らないと原因がわからず時間を消費する。同じ構成で詰まっている人のために記録しておく。
この記事を読む前に
正直に言うと、この記事に書いてあることの多くは、Claude in Chromeを使っていれば自分で解決する必要がない。
Claude in Chromeとは、ChromeブラウザにClaudeを組み込む拡張機能だ。これを入れると、ブラウザ上で起きていることをClaudeがリアルタイムで確認しながら作業できる。「記事が表示されない」「変更が反映されない」といった問題が起きたとき、「なんか表示されないんだけど」と伝えるだけで、Claudeが原因を調べて対処してくれる。
それでもこの記事を書いたのは、何が起きているかを知っておくと、AIへの指示がより的確になるからだ。「キャッシュが残っているかもしれない」と一言添えるだけで、AIの動きが変わる。仕組みを知らなくていいが、知っていると便利だ。
1. UTC問題——記事が公開されない
最初にハマったのがこれだ。記事を書いてpushしたのに、サイトに表示されない。エラーも出ていない。ビルドは成功している。なのに記事が出てこない。
原因はHugoの日付処理にある。
Hugoはデフォルトで、記事のdateがビルド時刻より未来の場合、その記事をスキップする。問題は、Hugoがビルド環境（Cloudflare Pages）でUTC（協定世界時）を基準にしていることだ。
日本時間（JST）はUTCより9時間進んでいる。つまり日本時間の4月25日午前8時に記事のdateを設定すると、UTC換算では4月24日の23時になる。Cloudflare Pagesが深夜0時前後にビルドを実行した場合、Hugoからすると「まだ未来の記事」と判断されてスキップされる。
解決策：記事のdateは必ず前日以前の日付に設定する。
これだけで解決する。地味だが、知らないと原因が全くわからない。Claude in Chromeを使っている場合は「記事が表示されないんだけど」と伝えればClaudeが気づいて修正してくれる。
2. エンコーディング問題——文字化けや謎のエラー
Markdownファイルを編集していると、稀に謎のビルドエラーが発生することがある。記事の内容は正しいはずなのに、Hugoが読み込めないというエラーだ。
原因はファイルのエンコーディングにある。
WindowsのメモやPowerShellで作成したファイルは、デフォルトでBOM付きUTF-8またはCRLF改行になることがある。HugoはBOMなしUTF-8・LF改行を期待しているため、これが混在するとエラーが起きる。
解決策：ファイルはBOMなしUTF-8・LF改行で保存する。
Claude Codeを使って記事ファイルを作成する場合はこの問題は発生しにくい。「ファイルを作って」と頼めばClaudeが適切な形式で作成してくれる。Windowsのツールで直接編集する場合だけ注意が必要だ。
3. キャッシュ問題——変更が反映されない
ビルドは成功した。でもサイトを見ても変更が反映されていない。
これはCloudflareのキャッシュが原因だ。Cloudflare Pagesは配信するファイルをエッジサーバーにキャッシュする。新しいデプロイが完了しても、キャッシュが古いファイルを返し続けることがある。
解決策：Cloudflareの「全てを浄化する」を実行する。
Cloudflareダッシュボード →「キャッシング」→「構成」→「全てを浄化する」
Claude in Chromeを使っている場合は「反映されてないんだけど」と伝えるだけで、Claudeがダッシュボードを開いてキャッシュを浄化してくれる。実際にこのブログの運営でも何度もやってもらった。
まとめ
| 問題 | 原因 | 解決策 |
|---|---|---|
| 記事が表示されない | HugoのUTC基準の日付判定 | dateを前日以前に設定 |
| 謎のビルドエラー | BOM付きUTF-8またはCRLF改行 | BOMなしUTF-8・LF改行で保存 |
| 変更が反映されない | Cloudflareのキャッシュ | 「全てを浄化する」を実行 |
どれも初見では原因がわかりにくい。ただClaude in Chromeがあれば「なんかおかしい」と言うだけで大体解決する。仕組みを知りたい人向けの記録として残しておく。