Cloudflare Pages静的サイトデプロイ完全ガイド：5大フレームワークの設定と落とし穴

午前2時、ブログの最初の記事を書き終え、期待に胸を膨らませて「デプロイ」ボタンをクリックしました。3分後、Cloudflare Pagesが「Success」と表示。ワクワクしながらURLを開くと……画面は真っ白。F12でコンソールを開くと、404エラーの山。

正直、初めてAstroブログをデプロイした時は絶望しました。Googleで「Cloudflare Pages デプロイ失敗」と検索しても、答えはバラバラ。「ビルドコマンドが違う」「出力ディレクトリが間違っている」「設定ファイルを変えろ」……数時間格闘した末、原因は単純な設定ミスでした。出力ディレクトリを public にしていたのですが、Astroのデフォルトは dist だったのです。

その後、友人のHugoやHexoブログのデプロイを手伝う中で気づきました。デプロイ失敗の9割は、「ビルドコマンド」と「出力ディレクトリ」の設定ミスが原因です。フレームワークごとにデフォルト設定が異なるため、適当にコピペすると痛い目に遭います。

Alibaba Cloud - 開発者向けクラウドの第一候補、ライトサーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

この記事では、Astro, Hugo, Hexo, Gatsby, Eleventyという5大静的サイトフレームワークのCloudflare Pagesにおける正確な設定値と、「画面が真っ白」「ビルド失敗」といったトラブルの解決法を解説します。これさえ読めば、Gitから10分で公開まで辿り着けます。

なぜCloudflare Pagesなのか？（2025年の状況）

私が静的ブログにCloudflare Pagesを推す理由はシンプルです。

無料、かつ爆速。
Cloudflareは世界中300以上のデータセンターを持っています。GitHub PagesやVercelも素晴らしいですが、特にアジア圏からのアクセス速度と安定性において、Cloudflare Pagesは群を抜いています。帯域幅の制限もなく、ビルド回数も無制限です。

Git連携が超便利。
GitHubやGitLabと連携すれば、git push するだけで自動的にビルド・デプロイが走ります。Pull RequestごとにプレビューURLを発行してくれる機能は、記事の校正やデザイン確認に神がかり的に便利です。

SSL証明書もカスタムドメインも無料。
面倒な証明書更新作業は一切不要。独自ドメインの設定もDNSレコードを追加するだけで完了します。

注意点：2025年のプラットフォーム方針
Cloudflareは2025年4月、プラットフォーム戦略を調整し、Cloudflare Workers を主力として推進し始めました。Pagesは「メンテナンスモード」に近い状態となり、大きな新機能追加は見込めません。
しかし、静的ブログのホスティングとしては、依然としてPagesが最適解です。複雑なバックエンド処理が必要ならWorkersへの移行を検討すべきですが、ブログやドキュメントサイトならPagesで何の問題もありません。安心して使い続けてOKです。

5大フレームワークの鉄板設定リスト（保存版）

ここが本記事の核です。迷ったらこの表を見てください。

クイック設定表

各フレームワークの注意点を詳しく見ていきましょう。

Astro の設定

私が現在メインで使っているフレームワークです。
標準設定:

• ビルドコマンド: npm run build (または astro build)
• 出力ディレクトリ: dist

SSG（静的生成）ならこれで完璧です。もしSSR（サーバーサイドレンダリング）を使う場合は、@astrojs/cloudflare アダプターをインストールし、astro.config.mjs に以下を追加する必要があります。

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

import cloudflare from '@astrojs/cloudflare';
export default {
  output: 'server',
  adapter: cloudflare()
};

Hugo の設定（ハマりポイントNo.1）

Hugoは落とし穴が深いです。
標準設定:

• ビルドコマンド: hugo (または hugo -b $CF_PAGES_URL)
• 出力ディレクトリ: public
• 必須環境変数: HUGO_VERSION = 0.143.1 (使用するバージョンに合わせて)

最大の罠: Cloudflare Pagesがデフォルトで使用するHugoのバージョンは 0.54 (2019年の太古のバージョン) です。最近のテーマはほぼ100%動きません。必ず環境変数 HUGO_VERSION で新しいバージョンを指定してください。
また、baseURL 問題を避けるため、ビルドコマンドを hugo -b $CF_PAGES_URL にすると、プレビュー環境でもリンクが壊れません（Cloudflareが自動でURLを注入してくれます）。

Hexo の設定

老舗ですが、依然として根強い人気があります。
標準設定:

• ビルドコマンド: hexo generate (または hexo g)
• 出力ディレクトリ: public

Node.jsのバージョンに敏感なテーマが多いです。ビルドが失敗する場合、環境変数 NODE_VERSION を 18.17.0 や 20.0.0 など、ローカル環境と同じバージョンに固定してください。

Gatsby の設定

標準設定:

• ビルドコマンド: gatsby build
• 出力ディレクトリ: public

特に難しいことはありません。最も安定してデプロイできるフレームワークの一つです。

Eleventy (11ty) の設定

標準設定:

• ビルドコマンド: npx @11ty/eleventy
• 出力ディレクトリ: _site

注意点は出力ディレクトリの先頭にアンダースコア _ が付くことです。これを忘れて site と書いてしまい、404になるケースが後を絶ちません。

Next.js の設定（2025年の新常識）

標準設定（新方式）:

Railway - モダンなデプロイプラットフォーム、煩わしい運用から解放、数分で公開

今すぐ始める →広告

• ビルドコマンド: npx opennextjs-cloudflare
• 出力ディレクトリ: .worker-next

重要: 以前主流だった @cloudflare/next-on-pages は非推奨になりました。現在は @opennextjs/cloudflare アダプターが推奨されています。古いチュートリアルを見て設定するとハマるので注意してください。
ただ、純粋な静的ブログならAstroやHugoの方が軽量で扱いやすいのが本音です。

実践：Gitリポジトリから公開までの完全フロー

では実際にデプロイしてみましょう。手元にGitHub/GitLabにプッシュ済みのコードがある前提で進めます。

ステップ1：Cloudflare Pagesでのプロジェクト作成

1. Cloudflare Dashboard にログイン。
2. 左メニューの Workers & Pages をクリック。
3. Create application → Pages タブ → Connect to Git を選択。

ステップ2：Git連携

1. Connect to Git をクリックし、GitHubまたはGitLabアカウントと連携します。
2. デプロイしたいリポジトリを選択し、Begin setup をクリック。

ステップ3：ビルド設定の入力（最重要）

ここが運命の分かれ道です。

1. Project name: ドメイン名になります（例: my-blog → my-blog.pages.dev）。
2. Production branch: 通常は main や master。
3. Framework preset: 使用しているフレームワークを選択すると、コマンドとディレクトリが自動入力されます。ただし、必ず上記の「鉄板設定リスト」と照らし合わせて確認してください。過信は禁物です。

ステップ4：環境変数の設定（Hugo/Hexoユーザーは必須）

Settings セクションを開き、Environment variables を追加します。

• Hugoの場合: HUGO_VERSION = 0.143.1
• Node系の場合（必要なら）: NODE_VERSION = 18.17.0

ステップ5：保存してデプロイ

Save and Deploy をクリック。ログが流れ始め、1〜3分程度で完了します。「Success! Your site is live!」と表示されれば勝利です。

トラーブルシューティング：困った時の処方箋

ケース1：ビルド失敗（Build Failed）

ログの最後の方を見てください。

• User error: Hugo version 0.54.0 does not support...
  → 環境変数 HUGO_VERSION の設定忘れです。
• Command not found や Cannot find module
  → package.json に依存関係が書かれていないか、インストールの段階で失敗しています。

ケース2：デプロイ成功したが画面が真っ白

9割方、出力ディレクトリ（Build output directory）の設定ミスです。

Alibaba Cloud - 開発者向けクラウドの第一候補、ライトサーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

• Astroなのに public と書いていないか？（正解は dist）
• Hugoなのに dist と書いていないか？（正解は public）
• Eleventyで site と書いていないか？（正解は _site）

ケース3：CSSや画像が読み込まれない

パス（Path）の問題です。

• サブディレクトリ（example.com/blogなど）にデプロイしている場合、フレームワーク側で baseURL や base の設定が必要です。
• Hugoの場合、ビルドコマンドを hugo -b $CF_PAGES_URL に変更すると、Cloudflareが自動的に正しいURLを埋め込んでくれるので解決することが多いです。

さらにプロっぽく：カスタムドメインと高速化

無事に公開できたら、次のステップへ。

カスタムドメインの設定

.pages.dev ドメインでもいいですが、独自ドメインは信頼の証です。
Pages のプロジェクトページ → Custom domains → Set up a custom domain から設定できます。CloudflareでDNS管理しているドメインなら、ものの数秒で設定完了し、SSLも自動適用されます。

ビルドの高速化

記事が増えるとビルド時間が伸びます。

• キャッシュの活用: Cloudflare Pagesはデフォルトで node_modules をキャッシュします。
• 不要な依存の削除: package.json を見直し、使っていないライブラリを削除しましょう。
• Hugoの最適化: --gc --minify オプションを付けると、ゴミ掃除と圧縮を同時に行ってくれます。

まとめ

静的ブログのデプロイは、**「正しい設定値を知っているか」**だけの勝負です。

• Astroなら dist
• Hugoなら public + 環境変数
• Eleventyなら _site

これさえ間違えなければ、Cloudflare Pagesは最強のブログホスティング環境になります。ぜひ、あなただけの素敵なブログを世界に公開してください。

4 min read · 公開日: 2025年12月1日 · 更新日: 2026年1月22日

Easton

技術開発