Cloudflare Pages で静的ブログをデプロイする完全ガイド：5 大フレームワークの設定で落とし穴を避ける

ブログの最初の記事を書き終え、「デプロイ」をクリック。3 分後、Cloudflare Pages に「デプロイ成功」と表示されたので、リンクをブラウザに貼り付けると——画面は真っ白。F12 でコンソールを開くと、404 が並んでいました。

初めて Astro ブログをデプロイしたときのあの徒労感。Google の答えはバラバラで、3〜4 時間試行錯誤した末、出力ディレクトリが public になっていたことが原因だと判明しました（Astro のデフォルトは dist）。

デプロイ失敗の 90% は、ビルドコマンドと出力ディレクトリの 2 点の設定ミスです。本記事では、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 のたびに Cloudflare がビルドとデプロイを実行します。Pull Request ごとにプレビューリンクも生成され、マージ前に見た目を確認できます。チームでの執筆にも便利です。

無料 SSL とカスタムドメイン付き。 証明書の面倒な設定は不要。独自ドメインの紐づけも簡単で、DNS は数分で反映されることが多いです。

ただし、先に伝えておきたいことがあります。Cloudflare は 2025 年 4 月にプラットフォーム方針を調整し、公式には Cloudflare Workers を主力に据え、Pages は大きな機能追加が見込めない「メンテナンス寄り」の状態に入りました。

とはいえ、静的ブログのデプロイには影響は小さいです。Pages は安定しており、機能も十分です。ブログやドキュメントサイト程度で、複雑な SSR やエッジ計算が不要なら、Pages が依然として最適です。動的機能や API ルート、高度なエッジ計算が必要なプロジェクトには Workers が向きます。

まとめると、今すぐ純粋な静的ブログを出すなら Pages で問題ありません。将来サーバー側の機能が必要になったら、そのとき Workers へ移行を検討すれば足ります。

5 大フレームワークの標準設定（本記事の核心）

ここからが本題です。5 大静的ブログフレームワークの正確な設定をまとめました。そのまま入力してください。

クイック設定表

この表はぜひブックマークしてください。各設定は実際に検証済みです。以下、フレームワークごとの注意点です。

Astro の設定

Astro は今いちばん好んで使っている静的ブログフレームワークです。性能も書き心地も良好です。

標準設定：

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

純粋な静的サイト（SSG）ならデフォルトのままで問題ありません。SSR を使う場合は @astrojs/cloudflare アダプターを入れ、astro.config.mjs に次を追加します。

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

出力ディレクトリを build などに変えることもできますが、デフォルトの dist のままが無難です。共同作業時に混乱しにくくなります。

export default {
  outDir: 'build'
};

Hugo の設定（最もハマりやすい）

Hugo の落とし穴は特に深いです。初回デプロイで一晩かかった経験があります。

標準設定：

KiloClaw - 企業向けマネージド OpenClaw、AI エージェントのオーケストレーションとスマートルーティングを加速

今すぐ始める →広告

• ビルドコマンド：hugo または hugo -b $CF_PAGES_URL
• 出力ディレクトリ：public
• 環境変数（必須）：HUGO_VERSION = 0.143.1（必要なバージョンに合わせる）

Cloudflare Pages のデフォルト Hugo は 0.54（2019 年） です。最近のテーマの多くは 0.80 以上、0.120+ を要求します。HUGO_VERSION を設定しないと、ほぼ確実にビルド失敗します。

設定方法は後述の実践フローで詳しく説明します。ここでは覚えておいてください。Pages プロジェクトの Settings > Environment variables で次を追加します。

• 変数名：HUGO_VERSION
• 値：0.143.1（0.143 のように 2 桁だけは不可）

.pages.dev ドメインを使う場合、内部リンクや RSS、sitemap を正しくするにはビルドコマンドを次のようにします。

hugo -b $CF_PAGES_URL

$CF_PAGES_URL は Cloudflare が自動注入する環境変数で、デプロイ環境に合った URL になります。

Hexo の設定

Hexo は老舗ですが、設定は比較的シンプルです。

標準設定：

• ビルドコマンド：hexo generate（hexo g でも可）
• 出力ディレクトリ：public

大きな問題は少ないですが、テーマやプラグインが Node.js バージョンに依存することがあります。ビルド失敗時は環境変数を試してください。

• 変数名：NODE_VERSION
• 値：14.3 または 18.17.0（ローカルの node -v に合わせる）

Gatsby の設定

Gatsby は最も手間がかかりにくい部類です。

標準設定：

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

これだけです。友人の Gatsby ブログを何度かデプロイしましたが、問題は出ませんでした。

Eleventy の設定

Eleventy（11ty）は軽量な静的サイトジェネレーターです。

標準設定：

• ビルドコマンド：npx @11ty/eleventy
• 出力ディレクトリ：_site（アンダースコア付き）

site と書いてしまうミスが非常に多いです。出力を変える場合はルートに .eleventy.js を置きます。

module.exports = function(eleventyConfig) {
  return {
    dir: {
      output: "public"
    }
  };
};

Next.js の設定（2025 年の変化）

Next.js でブログを組む場合、2025 年の変更に注意が必要です。

標準設定（2025 年新方式）：

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

重要：以前の @cloudflare/next-on-pages は非推奨です。@opennextjs/cloudflare を使います。古いチュートリアルはスキップしてください。

1. npm install @opennextjs/cloudflare
2. ビルドコマンド：npx opennextjs-cloudflare
3. 出力：.worker-next

純粋な静的ブログだけなら、Next.js より Astro や Hugo の方が軽量で速いことが多いです。

実践：Git リポジトリから公開までの完全フロー（手順付き）

設定がわかったら、ゼロからデプロイします。全体でおよそ 10 分です。

準備

始める前に次を確認します。

1. コードが GitHub または GitLab にプッシュ済み — リポジトリで最新コードを確認
2. package.json がある（Node.js プロジェクト）— 依存がすべて記載されているか。ローカルだけに入っているパッケージがないか
3. .gitignore — node_modules、dist、public などが除外されているか。ビルド成果物を push しない

node_modules まで Git に入れてしまい、デプロイで衝突した例もあります。.gitignore を一度見直してください。

詳細デプロイ手順

ステップ 1：Cloudflare にログインし Pages を開く

dash.cloudflare.com でログイン（無ければ無料登録）。左メニューの Workers & Pages → 右上 Create application。

ステップ 2：「Git に接続」を選択

• Connect to Git — GitHub/GitLab から自動デプロイ（こちら）
• Direct Upload — 手動アップロード（非推奨）

Connect to Git を選び、GitHub または GitLab を選択します。

ステップ 3：アクセス権の付与

初回は Cloudflare が Git にアクセスする承認が必要です。Sign in で GitHub/GitLab の認可画面へ。

全リポジトリを開きたくない場合は Only select repositories で特定リポジトリのみ許可できます。完了後 Cloudflare に戻ります。

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

15%割引を入手 →広告

ステップ 4：デプロイするリポジトリを選択

一覧からブログプロジェクトをクリック。見つからない場合は更新するか、再承認してください。

ステップ 5：ビルド設定（最重要）

• Project name：.pages.dev の一部（例：my-blog → my-blog.pages.dev）
• Production branch：通常 main または master
• Framework preset：フレームワークを選ぶか None

Build settings（前の表どおり）：

• Build command
  • Astro: npm run build
  • Hugo: hugo または hugo -b $CF_PAGES_URL
  • Hexo: hexo generate
  • Gatsby: gatsby build
  • Eleventy: npx @11ty/eleventy
  • Next.js: npx opennextjs-cloudflare
• Build output directory
  • Astro: dist
  • Hugo: public
  • Hexo: public
  • Gatsby: public
  • Eleventy: _site
  • Next.js: .worker-next

Framework preset で自動入力されても、必ず手動で照合してください。

ステップ 6：環境変数（必要な場合）

Environment variables (advanced) → Add variable。

• Hugo（必須）：HUGO_VERSION = 0.143.1（小数点 3 桁まで）
• Hexo（必要なら）：NODE_VERSION = 14.3 または 18.17.0

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

Save and Deploy。ビルドログが流れ、通常 1〜3 分で完了します。

ステップ 8：結果の確認

「Success! Your site is live!」と表示され、プロジェクト名.pages.dev のリンクからサイトを開けます。

環境変数の詳細

デプロイ時に設定し忘れた場合や後から変更する場合：

1. Cloudflare Pages プロジェクトを開く
2. 上部 Settings
3. 左 Environment variables
4. Add variable → 保存

よく使う環境変数：

• HUGO_VERSION：Hugo のバージョン（例 0.143.1）
• NODE_VERSION：Node.js（例 18.17.0）
• CF_PAGES_URL：Cloudflare が自動提供。baseURL 用に手動設定不要

重要：環境変数を変えたら再デプロイが必要です。Deployments で最新デプロイの ⋮ → Retry deployment。

プレビューデプロイ（Preview Deployments）

Pull Request を作成すると、Cloudflare が自動でプレビュー URL を生成します。GitHub で PR を作った段階で、そのブランチのビルド結果を別 URL で確認でき、問題なければ main へマージできます。複数人でブログを書くときのレビューに便利です。

困ったときは？よくあるエラーと切り分け

デプロイ中のトラブルは、だいたい次の 3 パターンで 95% カバーできます。

問題 1：ビルド失敗（Building Failed）

症状：「Building」のまま失敗し、赤いエラーアイコン。

まずログを見ます。いきなり再デプロイしないでください。

切り分け：

1. ビルドログ

   • View build log または Deployment details
   • 末尾の赤文字を確認（最後の数行が手がかり）

2. ビルドコマンド

   • Settings > Build & deployments の Build command
   • 例：npm run build を npm build（run 抜け）にしていないか

3. 依存関係

   • Cannot find module / Command not found なら package.json を確認
   • ローカルだけに入れ、npm install --save していない可能性

4. フレームワークのバージョン

   • Hugo：未設定の HUGO_VERSION が原因のことが多い。「Theme requires Hugo Extended version」など
   • Hexo：NODE_VERSION をローカルと揃える

実例：友人の Hugo ブログで「Hugo version 0.54.0 does not support this theme」。HUGO_VERSION = 0.120.0 を追加して再デプロイしたらすぐ成功しました。

問題 2：画面真っ白（最多）

症状：デプロイ成功だがページが空白。F12 で 404 が並ぶ。

90% は出力ディレクトリの誤りです。

切り分け：

1. F12

   • Console でエラー
   • Network を更新して 404 リソース
   • Sources でファイル構造

2. 出力ディレクトリ（約 90%）

   • Settings > Build & deployments の Build output directory
   • Astro：public ではなく dist
   • Hugo：dist ではなく public
   • Eleventy：site ではなく _site

3. baseURL / publicPath

   • サブパス（example.com/blog）なら baseURL が必要
   • Hugo：hugo -b $CF_PAGES_URL
   • Astro：astro.config.mjs の base: '/blog'
   • Vue/React：publicPath: './' など

4. SPA のルーティング

   • Vue Router / React Router の history モードでリロード時 404

   • hash モードにするか、ルートに _redirects：

     /* /index.html 200

実例：自分の Astro ブログで出力を public にしていた。dist に直したら解決しました。単純な設定ミスであることも多いです。

問題 3：スタイルやリソースの読み込み失敗

症状：ページは出るが CSS が効かず、画像も表示されない。

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

今すぐ始める →広告

切り分け：

1. Network タブで CSS・JS・画像が 404 か、パスが正しいか
2. パスの問題
   • /assets/style.css のような絶対パスはサブパスデプロイで壊れやすい
   • Astro：import でリソースを扱う
   • Hugo：.RelPermalink や absURL
   • Hexo：url_for()
3. 外部 CDN
   • jsDelivr などがブロックされていないか。必要なら国内 CDN へ

実例：Hexo ブログで CSS パスが /css/style.css だが実体は /blog/css/。サブパスデプロイで _config.yml の url と root を直し、root: /blog/ で再生成して解決しました。

クイックチェックリスト

困ったらこの順で確認します。

1. ✓ ビルドログのエラー
2. ✓ ビルドコマンド（設定表と照合）
3. ✓ 出力ディレクトリ（設定表と照合）
4. ✓ 環境変数（Hugo は HUGO_VERSION 必須）
5. ✓ ブラウザ F12（コンソール・ネットワーク）
6. ✓ .gitignore（ビルド成果物を push していないか）
7. ✓ ローカルで npm run build や hugo が通るか

それでも解決しなければ、Cloudflare コミュニティや公式 Troubleshooting を参照してください。

発展：ブログをよりプロらしく

公開できたら、次の一手です。どれも難しくありませんが、体験は大きく変わります。

カスタムドメインの紐づけ

.pages.dev でも動きますが、独自ドメインの方が信頼感があります。Cloudflare は SSL も無料です。

手順：

1. レジストラ（GoDaddy、お名前.com など）でドメイン取得
2. Pages プロジェクトの Custom domains
3. Set up a custom domain で blog.example.com などを入力
4. 表示された DNS レコードをレジストラ側に追加
5. 数分〜数時間で反映
6. HTTPS は自動設定

ドメインの DNS を Cloudflare で管理していると、より速く自動設定できることが多いです。

ビルドの高速化

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

1. キャッシュ — Pages は node_modules をキャッシュ。毎回フルダウンロードしていないか確認
2. 依存の整理 — package.json から未使用パッケージを削除。CDN で足りるライブラリは入れない
3. 並列・オプション — Hugo の --gc、Astro の experimental.contentCollectionCache など
4. ブランチ戦略 — 日常は dev、公開時だけ main へマージし、本番ビルドの回数を減らす

パフォーマンス監視と分析

Analytics タブで次を確認できます。

• リクエスト数
• 帯域幅
• 国別アクセス
• トレンド

Web Vitals で LCP や INP なども見られ、画像圧縮や遅延読み込みの改善に役立ちます。

自動化ワークフロー

GitHub Actions と組み合わせる例：

• 予約投稿 — 指定日時に自動公開
• sitemap 送信 — デプロイ後に検索エンジンへ
• 画像圧縮 — push 前に自動圧縮

必須ではありませんが、運用の手間は減らせます。コミュニティのテンプレートも豊富です。

まとめ

静的ブログのデプロイは、難しく見えて核心はシンプルです。ビルドコマンドと出力ディレクトリを正しくすれば、問題の 90% は避けられます。

もう一度、保存用の表です。

困っても、多くは設定の打ち間違いです。ビルドログを見て、本記事のチェックリストと照らし合わせてください。

今すぐ試してみてください。 Cloudflare Pages を開き、Git を接続し、正しい設定を入れれば、10 分後にはブログが公開できます。

役に立ったら、デプロイで悩んでいる友人にも共有してください。ここにない問題があればコメントで教えてください。他の読者の助けにもなります。

デプロイ成功と、楽しい執筆を。