cloudflare-pages

Cloudflare Pages

静的サイトを Cloudflare Pages にデプロイできます。プロジェクトの作成、カスタムドメインの追加、CI/CD の設定、デプロイの確認に対応しています。フレームワークを問いません。Hugo、Astro、Next.js、Nuxt、SvelteKit、または静的出力を生成する任意のビルドツールで利用できます。

前提条件

要件	入手方法
wrangler CLI	npm i -g wrangler を実行し、その後 wrangler login を実行します（ブラウザーで OAuth が開きます）
Cloudflare アカウント	dash.cloudflare.com — 無料プランで利用できます
アカウント ID	ダッシュボード → 任意のゾーン → サイドバーの Overview、または wrangler whoami
API トークン（CI/CD）	ダッシュボード → API Tokens → 「Edit Cloudflare Workers」テンプレート（Pages を含みます）
DNS API トークン	ダッシュボード → API Tokens → Custom → Zone:DNS:Edit（API 経由でカスタムドメインを追加する場合のみ）
ゾーン ID	ダッシュボード → ドメイン → サイドバーの Overview（カスタムドメインの場合のみ）

クイックデプロイ

CI/CD をまだ設定していない場合に、手動で一度だけデプロイする方法です。

# 1. Build your site
<your-build-command>          # e.g. hugo --minify, npm run build

# 2. Deploy output directory
wrangler pages deploy <output-dir> --project-name <project-name>

デプロイごとに一意のプレビュー URL が発行されます。production ブランチへの最新のデプロイが、<project>.pages.dev のライブサイトになります。

セットアップの全手順

ステップ 1 — Pages プロジェクトを作成する

bash scripts/setup-pages-project.sh <project-name> "<build-command>" <output-dir> [branch]

wrangler pages project create を実行し、生成された *.pages.dev の URL を表示します。branch 引数のデフォルトは main です。

手動で行う場合：

wrangler pages project create <project-name> --production-branch main

ステップ 2 — デプロイする

ビルドしてデプロイします：

<your-build-command>
wrangler pages deploy <output-dir> --project-name <project-name>

ステップ 3 — カスタムドメインを追加する

# Set required environment variables
export CLOUDFLARE_ACCOUNT_ID="<your-account-id>"
export CLOUDFLARE_API_TOKEN="<pages-edit-token>"
export CLOUDFLARE_ZONE_ID="<your-zone-id>"
export CLOUDFLARE_DNS_TOKEN="<dns-edit-token>"   # optional, falls back to API_TOKEN

bash scripts/add-custom-domain.sh <custom-domain> <project-name>

スクリプトは次の 2 つの操作を実行します：

1. Cloudflare API 経由で、Pages プロジェクトにドメインを 登録 します
2. <project>.pages.dev を参照するプロキシ済み CNAME DNS レコードを 作成 します

どちらの操作も冪等で、何度でも安全に再実行できます。

ステップ 4 — CI/CD を設定する

Hugo、Astro、Next.js、汎用 npm ビルド向けの GitHub Actions ワークフロー全体については、references/ci-cd-templates.md を参照してください。

必要な GitHub シークレット：

シークレット	値
CLOUDFLARE_API_TOKEN	「Edit Cloudflare Workers」権限を持つ API トークン
CLOUDFLARE_ACCOUNT_ID	Cloudflare アカウント ID

次の場所で設定します：Repository → Settings → Secrets and variables → Actions → New repository secret

ロールバック

# List recent deployments
wrangler pages deployment list --project-name <project-name>

# Rollback: checkout previous commit, rebuild, redeploy
git checkout <commit-hash>
<your-build-command>
wrangler pages deploy <output-dir> --project-name <project-name>

# Return to latest
git checkout main

デプロイを確認する

export CLOUDFLARE_ACCOUNT_ID="<your-account-id>"
export CLOUDFLARE_API_TOKEN="<your-token>"

bash scripts/verify-deployment.sh <project-name> [custom-domain]

以下が表示されます：最新のデプロイ状況（色分け表示）、直近 5 件のデプロイ一覧、カスタムドメインの SSL 状況、*.pages.dev への HTTP 200 チェック。

スクリプトの一覧

スクリプト	用途	必須の環境変数
setup-pages-project.sh	wrangler 経由で Pages プロジェクトを作成	CLOUDFLARE_ACCOUNT_ID
add-custom-domain.sh	ドメインを登録し、CNAME を作成	CLOUDFLARE_ACCOUNT_ID、CLOUDFLARE_API_TOKEN、CLOUDFLARE_ZONE_ID
verify-deployment.sh	デプロイ状況、SSL、HTTP を確認	CLOUDFLARE_ACCOUNT_ID、CLOUDFLARE_API_TOKEN

トークン一覧

操作	必要なトークン	スコープ	使用場所
wrangler pages deploy	Wrangler OAuth	wrangler login 経由で自動設定	ローカル CLI、CI/CD
Pages にカスタムドメインを登録	API トークン	Account:Cloudflare Pages:Edit	add-custom-domain.sh
CNAME DNS レコードを作成	DNS API トークン	Zone:DNS:Edit	add-custom-domain.sh
CI/CD デプロイ（GitHub Actions）	API トークン	「Edit Cloudflare Workers」テンプレート	GitHub Secrets
デプロイを照会	API トークン	Account:Cloudflare Pages:Read	verify-deployment.sh

ヒント： よりシンプルに設定するには、Pages:Edit と DNS:Edit の両方のスコープを持つ単一の API トークンを使用できます。その場合は CLOUDFLARE_API_TOKEN を設定し、CLOUDFLARE_DNS_TOKEN は省略してください。

トラブルシューティング

問題	原因	対処方法
wrangler: command not found	wrangler がインストールされていません	npm i -g wrangler
Authentication error	OAuth の有効期限切れ、またはトークンが正しくありません	wrangler login（再認証）
カスタムドメインが「pending」のまま	CNAME レコードがない、または正しくありません	DNS を確認します。CNAME は <project>.pages.dev を指す必要があります
SSL がプロビジョニングされない	ドメインが Cloudflare 経由でプロキシされていません	CNAME プロキシを「Proxied」（オレンジ色の雲）に設定します
カスタムドメインで 522 エラーが発生する	DNS レコードは存在しますが、ターゲットが正しくありません	古いレコードを削除し、add-custom-domain.sh を再実行します
デプロイは成功するが、サイトが 404 になる	出力ディレクトリが正しくありません	ビルド出力ディレクトリがデプロイ先と一致していることを確認します
CI/CD デプロイが失敗する	GitHub シークレットがありません	CLOUDFLARE_API_TOKEN と CLOUDFLARE_ACCOUNT_ID を追加します

エージェント型ワークフローとバイブコーディング

• 反復的なデプロイ： 初回の実行で CI/CD の設定や DNS の反映が完璧になるとは限りません。設定案を作成するか、手動でデプロイし、Cloudflare Pages のログやステータスチェックを確認します。特定のビルドエラーやプロキシの問題を切り分け、設定を一度に 1 つだけ変更して、サイトが公開されるまで再デプロイします。
• バイブコーディング： デプロイ用スクリプトと GitHub Actions のワークフローは、ライブリポジトリでテストする前にローカルでコミットしておきます。これにより、パイプラインが壊れた場合に簡単にロールバックできます。

アンチパターン

• Cloudflare の Git 統合は使用しないでください — 直接アップロードには wrangler pages deploy を使用します。Git 統合はこのワークフローにメリットがない一方で、複雑さを増します。
• 同じサイトに対して複数のプロジェクトを作成しないでください — 1 つのプロジェクトに複数のカスタムドメインを設定できます。
• CNAME の手順を省略しないでください — DNS レコードを設定せずに Pages にドメインを登録すると、「pending」のままになり、いつまでも解消されません。
• プロキシされていない CNAME レコードは使用しないでください — Cloudflare の SSL と CDN は、オレンジ色の雲（プロキシ）が有効な場合にのみ機能します。
• スクリプトにアカウント ID をハードコードしないでください — 必ず環境変数を使用します。