Cloudflare Pagesで静的Webアプリをホストする方法：構築設定やカスタムドメインの設定手順

Cloudflare Pagesホスティングを使用すると、フロントエンドの開発チームはサーバー運用の負担なしに、高速で安全なWebアプリを簡単に公開できます。開発者は、静的Webアプリケーション、シングルページアプリ（SPA）、サーバーサイドレンダリング（SSR）フレームワークをデプロイするための、高性能なエッジネイティブプラットフォームであるCloudflare Pages を活用できます。Gitリポジトリと直接連携させることで、Cloudflareはビルドパイプラインを自動化し、プレビュー環境を生成し、アセットを世界各地のエッジサーバーから瞬時に提供します。このガイドでは、Gitの接続方法、ビルド設定の調整、カスタムドメインの割り当て、およびリダイレクトの定義手順についてわかりやすく解説します。

主なまとめ：

• エッジネイティブなフロントエンドアプリの展開：Cloudflareのグローバルネットワークを介して世界中にアセットを配信し、1秒未満の応答速度を実現します。
• 自動化されたGit連携：Gitリポジトリを連携させ、コミットのたびに自動ビルドを実行してプレビュー用の検証URLを自動生成します。
• フレームワークに合わせたビルド設定：React、Vue、Next.js、Hugo、Astroなどに最適な出力ディレクトリとビルドコマンドを設定します。
• リダイレクトとヘッダーの設定：公開フォルダ内のシンプルなテキストファイル _redirects および _headers を用いて、挙動を制御します。
• カスタムドメインの割り当て：Cloudflareが管理する、無料で自動更新されるSSL証明書を利用してドメインを設定します。

Cloudflare Pagesとは

Cloudflare Pagesは、NetlifyやVercelに類似した、フロントエンド開発者向けのサーバーレスホスティングプラットフォームであり、Cloudflareのグローバルインフラストラクチャ上に直接構築されています。

ファイルを単一のクラウドサーバーでホストするのではなく、HTML、CSS、JavaScript、および画像を世界中のエッジロケーションに分散配置します。ユーザーがサイトにアクセスすると、物理的に最も近い拠点からアセットがロードされ、ネットワークレイテンシ（遅延時間）が最小限に抑えられます。サーバーサイドの動的処理を必要とするプロジェクトでは、PagesをCloudflare Workersと組み合わせてバックエンドのサーバーレス関数を呼び出すことができます。他のエッジコンピューティングサービスとの違いについては、Cloudflare Pages vs Workersの比較ガイド をご覧ください。

前提条件

作業を開始する前に、以下の準備ができているか確認してください。

• Gitリポジトリ：GitHubまたはGitLab上で管理されているプロジェクトのリポジトリ（またはビルド後の成果物ファイルを直接アップロードする準備）。
• 静的ファイルを生成するフレームワーク：React (Vite)、Vue、Astro、SvelteKit、Hugo、あるいは生のHTML。サーバーサイドで実行されるアプリも、Pages Functionsを介して動作します。
• ローカルでの正常なビルドの確認：連携前にローカル環境でビルドコマンド（例：npm run build）を実行し、エラーなしで出力ディレクトリが生成されることを確認してください。
• Cloudflareの無料アカウント：無料プランの利用にクレジットカードの登録は不要です。
• Node.jsのローカルインストール（推奨）：ローカルでビルドを再現したり、コマンドラインツールであるWranglerを使用したりするために必要です。

事前のローカルビルドの確認により、デプロイ時のエラーに悩む時間を大幅に削減できます。自身のPC上で正常に動作しないコードは、Cloudflareのビルド環境でも同様に失敗します。まずはローカルでのビルドエラーを取り除きましょう。

ステップ 1: Gitリポジトリの接続

まず、Cloudflareダッシュボードにログインし、Compute > Pages に移動して プロジェクトの作成 をクリックします。

Gitに接続を選択して、GitHubまたはGitLabアカウントを連携します。対象となる静的Webアプリのリポジトリを選択してください。この連携により、継続的インテグレーション（CI）パイプラインが構築されます。本番ブランチにコードをプッシュするたびに、Cloudflareが自動的に最新のソースコードをビルドしてリリースします。他の開発ブランチへのコミットの際には、一意の「プレビューURL」が生成されるため、変更内容をマージ前にブラウザでテストできます。

ステップ 2: ビルド設定の構成

Cloudflare Pagesは、主要な静的サイトジェネレーターやフロントエンドフレームワークをネイティブにサポートしています。セットアップウィザードでは、構成スタックに合わせて以下の内容を設定します。

• ビルドコマンド（Build command）：package.jsonで定義されているビルドスクリプト（例：npm run build または hugo --minify）。
• ビルド出力ディレクトリ（Build output directory）：コンパイルされた静的アセットが出力されるフォルダ（例：dist、build、public）。
• 環境変数（Environment variables）：ビルド時にAPIキーや構成設定の変数が必要な場合、ここに定義します。

Cloudflareは多くのフレームワークの設定を自動検出しますが、念のためプリセットが正しいか確認することで初回ビルドの失敗を防ぐことができます。標準的な構成は以下の通りです。

Node.jsのバージョンを固定する。「ローカルでは動作するが、Cloudflare上でビルドが失敗する」という問題の大部分は、ビルド環境のNode.jsバージョンとプロジェクトの想定バージョンのミスマッチが原因です。ダッシュボードの環境変数で以下のように明示的に指定してください。

1NODE_VERSION = 20

または、リポジトリのルートに .node-version ファイルをコミットして設定します。

120

ステップ 3: リダイレクトとカスタムヘッダーの適用

React Routerなどを使用するシングルページアプリケーション（SPA）や、古いURL構造からのリダイレクトを管理するためには、ルーティングルールを設定する必要があります。Pagesでは、出力ディレクトリに単純なプレーンテキストファイルを配置するだけでこれを実現できます。

リダイレクトルール（_redirects）

ビルド出力の公開フォルダ（publicなど）に _redirects という名前のファイルを配置します。React SPAでクライアント側のルーティングを適切に動作させるために、以下のフォールバックルールを記述します。

1/*  /index.html  200

これにより、すべてのアクセスが index.html に転送され、JavaScriptのフロントエンドルーターが要求されたパスを処理できるようになります。

ルールの評価は上から順に行われ、最初に一致したものが適用されます。そのため、特定の明確なリダイレクトは、全体をカバーするフォールバックルールよりも上部に記述する必要があります。

1# Permanent redirect for a moved page
2/old-pricing   /pricing            301
3
4# Redirect an entire section, preserving the sub-path
5/blog/*        /articles/:splat    301
6
7# SPA fallback (must come last)
8/*             /index.html         200

:splat プレースホルダーは、元のパスで一致した部分を転送先にそのまま引き継ぎます。無料プランでは、1プロジェクトあたり最大2,000行のリダイレクトルールを設定できます。これを超える場合は、Pages FunctionsのロジックやBulk Redirects機能に移行してください。

カスタムヘッダー（_headers）

セキュリティルール、リファラーポリシー（Referrer-Policies）、またはカスタムキャッシュコントロールを適用するために、 _headers ファイルを作成します。

1/*
2  X-Frame-Options: DENY
3  X-Content-Type-Options: nosniff
4  Referrer-Policy: strict-origin-when-cross-origin

このファイルは、キャッシュポリシーの最適化にも最適です。名前がハッシュ化された画像やJSファイルなどの変更されないアセット（immutable assets）は1年間キャッシュさせ、HTMLファイルはユーザーが常に最新のビルドを取得できるようキャッシュ時間を最小限に設定します。

1/assets/*
2  Cache-Control: public, max-age=31536000, immutable

これらのルールが従来のWebサーバーと比べてどのように機能するかについては、Cloudflare Workersを用いたサーバーレスAPIの構築 を参照してください。

ステップ 4: カスタムドメインの紐付け

デプロイが完了すると、Cloudflareは自動的にデフォルトのサブドメイン（例：your-project.pages.dev）を提供します。

独自のドメインを適用するには、Pagesプロジェクトの Custom Domains タブに移動し、希望するドメイン（例：yourcompany.com）を入力します。ドメインのDNSがCloudflareで管理されている場合、CNAMEレコードが自動設定され、無料で自動更新されるSSL証明書が即座に発行されます。ドメインの割り当て、DNS設定、あるいはサーバーセキュリティについてサポートが必要な場合は、Webサイトセキュリティ監査 ページをご覧ください。

ステップ 5: Wrangler CLIを使用した直接デプロイ

リポジトリからのGit自動ビルドは便利ですが、CloudflareのコマンドラインツールであるWranglerを使用して、自身のPCや既存のCI/CDパイプラインから直接ビルド済みフォルダをアップロードすることもできます。これは、GitHub ActionsやGitLab CI側でビルド処理が完了しており、生成された成果物だけをCloudflareにアップロードしたい場合に適しています。

Wranglerをインストールして認証します。

1npm install -g wrangler
2wrangler login

ローカルでビルドを実行し、出力ディレクトリを指定してプロジェクトにデプロイします。

1npm run build
2wrangler pages deploy ./dist --project-name=my-web-app

プロジェクトが未作成の場合、最初の実行時に自動作成されます。CI環境で非対話的にデプロイを実行するには、Wranglerのログインステップの代わりに、環境変数経由でAPIトークンを渡します。

1# .github/workflows/deploy.yml (excerpt)
2- name: Deploy to Cloudflare Pages
3  run: npx wrangler pages deploy ./dist --project-name=my-web-app
4  env:
5    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
6    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

直接アップロードを行うことで、Cloudflare側でのビルドステップをスキップできるため、環境の違いによるエラーを回避し、任意のツールチェーンを完全に管理できるようになります。

一般的な問題とトラブルシューティング

初回デプロイ時の問題の多くは、以下の典型的な原因によるものです。

• SPAのルート更新時に404エラーが発生する：クライアント側のルート（/dashboardなど）でブラウザを更新した際、「Nothing is here yet」と表示される場合、サーバー上にその物理ファイルが存在しないためです。 _redirects ファイルに /* /index.html 200 を設定し、そのファイルがソースフォルダではなく、ビルド後の出力フォルダに正しくコピーされているか確認してください。
• _redirects や _headers が反映されない：これらの制御用ファイルは、リポジトリに置くだけでなく、最終的に配信される公開フォルダに出力される必要があります。Vite、Astro、SvelteKitなどでは、ビルド時にそのままコピーされるように public/（または static/）フォルダにファイルを配置してください。
• ローカルではビルドできるがCloudflare上で失敗する：大半はNodeのバージョン相違、または環境変数の設定漏れが原因です。Nodeのバージョンを設定し、ビルドスクリプトが読み込む環境変数をダッシュボード上で正しく設定し直してください。
• ファイル制限超過、またはサイズが大きすぎる：1回のデプロイに含まれるファイル数は20,000個まで、1ファイルあたりの上限は25MiBです。大容量の画像や動画は静的バンドルに含めず、R2ストレージや外部の画像配信サービスを利用してください。
• リリース後のキャッシュの残り：ハッシュ名付きのアセットファイル（app.4f2c.jsなど）はキャッシュポリシーを設定できますが、index.htmlファイルはそうではありません。HTMLは短いキャッシュ時間を保つようにしてください。

テストと本番環境における考慮事項

Cloudflareは、本番以外のすべてのブランチおよびプルリクエストに対して、それぞれ専用のURL（例：abc123.my-web-app.pages.dev）で**プレビュー環境（preview deployment）**を生成します。プレビューは本番サイトと同じエッジネットワーク上で実行されるため、マージ前に変更内容を確認するための信頼できる環境となります。

実際のリリースにおいては、いくつかの機能が単なるホスティングと信頼性の高いワークフローとの差を生み出します。

• ロールバック：すべてのデプロイが保持されるため、問題のあるリリースは、ダッシュボードから以前のビルドを数秒で本番環境に再昇格させるだけで、再ビルドすることなく元に戻せます。
• 環境の分離：本番環境とプレビュー環境で異なる変数を設定し、プレビュー用のビルドが本番データではなくステージング用のAPIを参照するようにします。
• アナリティクスとCore Web Vitals：プライバシー重視でCookie不要のCloudflare Web Analyticsを有効にすると、サードパーティ製スクリプトを読み込むことなく、実際のユーザーのLCP、CLS、トラフィックを計測できます。
• プレビューのアクセス制御：プレビューURLはデフォルトで公開されています。ブランチが未公開の作業内容を含む場合は、Cloudflare Accessの背後に配置し、自分のチームだけがアクセスできるようにしてください。

これらを早い段階で整備しておくことで、プロジェクトが成長し、より多くの人がプッシュするようになっても、デプロイの予測可能性を保つことができます。

重要なまとめ

• Cloudflare Pagesは、静的WebアプリケーションをCloudflareのグローバルエッジネットワークでホストし、表示速度を最適化します。
• GitHubやGitLabを連携させることで、コード変更がコミットされるたびにデプロイを自動化できます。
• 使用するフレームワーク（React、Astro、Next.js、Hugoなど）に合わせて、ビルドコマンドと出力フォルダを設定します。
• 公開ディレクトリに _redirects と _headers テキストファイルを配置するだけで、簡単にURL転送やセキュリティ設定を行えます。
• 無料で自動更新されるSSL証明書を利用して、カスタムドメインをPagesプロジェクトに直接マッピングできます。

Webインフラストラクチャの最適化

高速で安全なフロントエンドを展開するには、適切なホスティングアーキテクチャとキャッシュルールを選択する必要があります。MecanikはWebサイト開発サービス を専門とし、専門的なテクニカルSEO監査サービス を提供しています。私たちは、Core Web Vitalsに最適化され、Cloudflare上にデプロイされる、カスタムのReact、Next.js、Astroプラットフォームを構築します。次のプロジェクトについてご相談されたい場合は、今すぐお問い合わせください。

よくある質問(FAQ)

Cloudflare Pagesホスティングとは何ですか？ フロントエンド開発者向けのサーバーレスホスティングプラットフォームであり、静的Webアプリケーション、React SPA、および静的サイトジェネレーター（AstroやHugoなど）のビルド成果物を、Cloudflareの高速なCDNを介してグローバルに提供します。

Cloudflare Pagesはサーバーサイドレンダリング（SSR）に対応していますか？ はい。PagesはSSRフレームワーク（Next.js、Astro、SvelteKitなど）に対応しており、ビルド処理の過程でサーバーロジックをサーバーレスなCloudflare Workersに自動変換して処理を実行します。

Cloudflare Pagesでリダイレクトを設定するにはどうすればよいですか？ ビルド出力の公開フォルダに _redirects というプレーンテキストファイルを作成し、転送元のパス、転送先のパス、およびHTTPステータスコードを記述します。

Cloudflare Pagesの利用は無料ですか？ はい。Cloudflare Pagesには非常に充実した無料枠が用意されており、帯域幅（転送量）制限なし、ビルド回数無制限、カスタムドメインの無料設定などが含まれているため、静的サイトのホスティングに極めて適しています。

Pagesプロジェクトにカスタムドメインを設定するにはどうすればよいですか？ プロジェクトダッシュボードの「Custom Domains」タブに移動し、所有するドメイン名を入力します。CloudflareがDNSの構成をサポートし、無料のSSL証明書を発行します。