既存Cloudflare PagesプロジェクトをDirect UploadからGit連携に移行する手順

概要

このガイドでは、既にDirect Uploadで運用中のCloudflare Pagesプロジェクトを、GitHub連携による自動デプロイに移行する手順を説明します。

なぜこの移行が必要か？

• 現状: wrangler pages deploy で手動デプロイ
• 問題点:
  • GitHubにpushしても自動デプロイされない
  • Pull Requestのプレビューデプロイが使えない
  • デプロイの度にコマンド実行が必要
• 解決策: Git連携に移行してプッシュだけで自動デプロイ

移行のリスクと注意点

⚠️ 重要な注意事項

1. プロジェクトの削除が必要
   • Direct Upload → Git連携への直接変更は不可
   • 一度プロジェクトを削除して作り直す必要がある
2. カスタムドメインの再設定
   • サブドメインやカスタムドメインを設定している場合は再設定が必要
   • DNS設定は保持されるが、Pages側の設定は削除される
3. 環境変数の再設定
   • 既存の環境変数は移行されない
   • 事前にメモしておく必要がある
4. デプロイメントURLの変化
   • プロジェクト名が変わる場合、xxx.pages.dev のURLも変わる
   • カスタムドメインを使用していれば影響なし

前提条件

• ✅ GitHubリポジトリが既に存在する
• ✅ リポジトリに最新のコードがpushされている
• ✅ Cloudflare Pagesプロジェクトが稼働中
• ✅ Cloudflareアカウントへのアクセス権限がある

移行手順

ステップ0: 現在の設定を記録（重要！）

移行前に、必ず現在の設定をメモしておきます。

0-1. カスタムドメイン・サブドメインの確認

1. Cloudflare Dashboard > Workers & Pages > プロジェクトを選択
2. Custom domains タブをクリック
3. 設定されているドメインをすべてメモ：

例:
- log.eurekapu.com

0-2. 環境変数の確認

1. Settings > Environment variables をクリック
2. すべての環境変数をメモ：

例:
NODE_VERSION = 22.6.0
PNPM_VERSION = 10.10.0
NUXT_PUBLIC_API_BASE = https://api.example.com
RESEND_API_KEY = re_xxxxxxxxxxxx

今回はなし

0-3. プロジェクト名の確認

現在のプロジェクト名をメモ：

例:
プロジェクト名: mdx-playground-web
デプロイURL: https://mdx-playground-web.pages.dev

重要: 同じプロジェクト名で作り直せば、.pages.dev のURLは変わりません。

ステップ1: GitHubリポジトリの準備

1-1. リポジトリの確認

# 現在のリモートリポジトリを確認
git remote -v

# 出力例:
# origin  https://github.com/your-username/your-repo.git (fetch)
# origin  https://github.com/your-username/your-repo.git (push)

1-2. 最新コードをプッシュ

# すべての変更をコミット
git add .
git commit -m "Prepare for Cloudflare Pages Git integration"

# mainブランチにプッシュ
git push origin main

1-3. GitHubリポジトリの確認

GitHubにアクセスして、最新のコードが反映されているか確認：

https://github.com/your-username/your-repo

ステップ2: 既存Cloudflare Pagesプロジェクトの削除

⚠️ 注意: この操作は取り消せません。必ずステップ0で設定を記録してから実行してください。

2-1. 現在のデプロイメントの確認

削除前に、現在のサイトが正常に動作していることを確認：

https://mdx-playground-web.pages.dev/

スクリーンショットを撮っておくと安心です。

2-2. カスタムドメインの削除（必須）

⚠️ カスタムドメインが設定されている場合、先に削除しないとプロジェクトを削除できません。

1. Custom domains タブを開く
2. 設定されているドメイン（例: log.eurekapu.com）の × または Remove をクリック
3. すべてのカスタムドメインを削除

2-3. プロジェクトの削除

1. Cloudflare Dashboard > Workers & Pages
2. 削除するプロジェクトを選択
3. Settings > Delete project
4. プロジェクト名を入力して確認
5. Delete をクリック

削除されるもの:

• ✅ デプロイメント履歴
• ✅ 環境変数
• ✅ カスタムドメイン設定（DNS設定は保持）
• ✅ ビルド設定

削除されないもの:

• ✅ GitHubリポジトリ
• ✅ DNSレコード（Cloudflare DNS使用時）
• ✅ ドメイン自体
  

ステップ3: Git連携で新規プロジェクト作成

3-1. 新規プロジェクト作成の開始

1. Cloudflare Dashboard > Workers & Pages
2. Create application をクリック
3. Pages タブを選択
4. Connect to Git をクリック

3-2. GitHubアカウントの接続

初回の場合:

1. Connect GitHub をクリック
2. Cloudflareに必要な権限を許可
3. リポジトリアクセスの選択：
   • All repositories（すべてのリポジトリにアクセス）
   • Only select repositories（特定のリポジトリのみ）← 推奨

既に接続済みの場合:

1. リポジトリ一覧から対象のリポジトリを選択

3-3. ビルド設定

重要: ここで正しく設定しないとビルドが失敗します。

⚠️ 重要な注意事項:

1. デプロイコマンドは true を推奨
   • Git連携ではCloudflareがビルド成果物を自動デプロイする
   • wranglerを使うと権限エラーやプロジェクト名不一致などの問題が発生する
   • true は「何もしないで成功」を意味するシェルコマンド
2. ビルドコマンドは必ず pnpm generate
   • npm run build や pnpm build ではなく pnpm generate を使用
   • nuxt build はSSRモードでビルドし、D1データベースが必要
   • nuxt generate は静的サイト生成で、すべてのコンテンツを事前レンダリング
   • 間違えると「Hello world」しか表示されない（問題11参照）

モノレポの場合の注意:

例: mdx-playground プロジェクトの場合
Root directory (パス): apps/web
Build command: pnpm install && pnpm generate
Deploy command: true
Build output directory: dist

3-4. 環境変数の設定

Environment variables セクションで、必須の環境変数を設定：

⚠️ NODE_VERSION=22 は必須:

• Cloudflareのデフォルトは Node.js 18
• 最新の Nuxt/Nuxt Content が依存する oxc-parser は Node.js 20.19.0 以上を要求
• NODE_VERSION=22 を設定しないとビルドが失敗する

環境の選択:

• Production: 本番環境のみ
• Preview: プレビュー環境のみ
• Production, Preview: 両方

3-5. デプロイの開始

1. Save and Deploy をクリック
2. 初回ビルドが開始される
3. ビルドログをリアルタイムで確認

ビルドログの確認方法:

• 進行中のデプロイメントをクリック
• View build log でログを確認

3-6. デプロイの成功確認

ビルドが成功したら、以下を確認：

# 新しいデプロイメントURL
https://your-project.pages.dev

サイトが正常に表示されるか確認してください。

ステップ4: カスタムドメインの再設定

ステップ0-1でメモしたカスタムドメインを再設定します。

4-1. カスタムドメインの追加

1. プロジェクトの Custom domains タブを開く
2. Set up a custom domain をクリック
3. ドメインを入力（例: log.eurekapu.com）
4. Continue をクリック

4-2. DNS設定の確認

Cloudflare DNSを使用している場合：

• 自動設定: CNAMEレコードが自動で追加される
• 確認：log.eurekapu.com → your-project.pages.dev

外部DNSを使用している場合：

タイプ: CNAME
名前: log (サブドメイン部分)
値: your-project.pages.dev

4-3. SSL証明書の発行待ち

• 証明書発行には最大24時間かかる場合がある
• 通常は数分で完了
• Status: Active になれば完了

4-4. 複数ドメインの設定

ステップ0-1でメモした他のドメインも同様に追加：

例:
- log.eurekapu.com → Active
- www.log.eurekapu.com → Active
- tax.eurekapu.com → Active

ステップ5: 自動デプロイの確認

5-1. テストコミット

# 簡単な変更を加える
echo "# Test" >> README.md

# コミット & プッシュ
git add .
git commit -m "Test automatic deployment"
git push origin main

5-2. 自動ビルドの確認

1. Cloudflare Dashboard > プロジェクト > Deployments タブ
2. 新しいデプロイメントが自動で開始されることを確認
3. ビルドログで成功を確認

5-3. プレビューデプロイのテスト

# 新しいブランチを作成
git checkout -b feature/test-preview

# 変更を加える
echo "# Preview Test" >> README.md

# プッシュ
git add .
git commit -m "Test preview deployment"
git push origin feature/test-preview

GitHub上でPull Requestを作成すると：

• ✅ プレビューURLが自動生成（例: https://abc123.your-project.pages.dev）
• ✅ PRコメントにURLとビルドステータスが投稿される

ステップ6: ブランチ制御の設定（オプション）

特定のブランチのみ自動デプロイしたい場合：

1. Settings > Builds & deployments
2. Branch deployment controls セクション

設定例1: mainブランチのみ本番デプロイ

Production branch: main
Preview deployments: None

設定例2: すべてのブランチでプレビュー作成

Production branch: main
Preview deployments: All branches

設定例3: 特定のブランチパターンのみ

Production branch: main
Preview deployments: Custom branches
Branch name pattern: feature/*

トラブルシューティング

問題1: ビルドが失敗する

原因1: Root directoryが未設定（モノレポ）

エラー例:

Could not find package.json

解決策:

Settings > Builds & deployments > Build configurations > Root directory を設定：

apps/web

原因2: Node.jsバージョンが古い

エラー例:

Node version 18.x is not supported

解決策:

環境変数に追加：

NODE_VERSION = 22.6.0

原因3: pnpmが認識されない

エラー例:

pnpm: command not found

解決策:

環境変数に追加：

PNPM_VERSION = 10.10.0

ビルドコマンドを修正：

# 悪い例
pnpm build

# 良い例
pnpm install && pnpm build

原因4: ネイティブバインディングが見つからない（Windows → Linux）

エラー例:

[error] Cannot find native binding.
Cannot find module '@oxc-parser/binding-linux-x64-gnu'

問題の原因:

ローカル環境（Windows）で生成した pnpm-lock.yaml にはWindows用のネイティブバインディングしか含まれていないため、Cloudflareのビルド環境（Linux）で失敗する。

解決策:

1. .npmrc に supportedArchitectures を追加：

node-options=--experimental-sqlite
supportedArchitectures.os=linux,win32,darwin
supportedArchitectures.cpu=x64,arm64

2. lockfileを再生成（Windows PowerShellの場合）：

Remove-Item -Recurse -Force node_modules
Remove-Item pnpm-lock.yaml
pnpm install

3. 変更をコミット・プッシュ

実際の対応ログ（2025-12-07）:

PS C:\Users\numbe\Git_repo\mdx-playground\apps\web> Remove-Item -Recurse -Force node_modules
PS C:\Users\numbe\Git_repo\mdx-playground\apps\web> Remove-Item pnpm-lock.yaml
PS C:\Users\numbe\Git_repo\mdx-playground\apps\web> pnpm install

Packages: +1326
Progress: resolved 1531, reused 1275, downloaded 57, added 1326, done

> nuxt-app@ postinstall C:\Users\numbe\Git_repo\mdx-playground\apps\web
> nuxt prepare

[@nuxt/content 6:24:39]  WARN  Deploying to Cloudflare requires using D1 database, switching to D1 database with binding DB.

◆  Types generated in .nuxt.

Done in 1m 5.9s using pnpm v10.10.0

結果: lockfileにLinux用のバインディングが含まれるようになり、Cloudflareでのビルドが成功するようになった。

問題2: カスタムドメインが反映されない

確認事項

1. DNS設定が正しいか

   # CNAMEレコードの確認
   dig log.eurekapu.com CNAME
   
   # 期待される出力
   log.eurekapu.com. 300 IN CNAME your-project.pages.dev.
   

2. SSL証明書のステータス
   Custom domains タブで Active になっているか確認
3. プロキシ設定（Cloudflare DNS使用時）
   • オレンジ雲アイコン = プロキシ有効（推奨）
   • グレー雲アイコン = DNS専用

解決策

証明書が Pending の場合：

• 最大24時間待つ
• DNS設定が正しいか再確認
• Cloudflareサポートに問い合わせ

問題3: 環境変数が反映されない

確認事項

1. Environment の選択
   • Production と Preview は別々
   • 両方で使う変数は両方に設定
2. 変数名の大文字小文字
   • 環境変数は大文字小文字を区別する
   • NODE_VERSION ≠ node_version
3. 再デプロイ
   • 環境変数を変更したら再デプロイが必要

解決策

# 環境変数を変更後、空コミットで再デプロイ
git commit --allow-empty -m "Trigger redeploy for env vars"
git push

問題4: プレビューデプロイが作成されない

確認事項

1. Branch deployment controls
   • Settings > Builds & deployments
   • Preview deployments が有効か
2. GitHubアプリの権限
   • Cloudflare Pagesがリポジトリにアクセスできるか
   • GitHub Settings > Applications > Cloudflare Pages で確認
3. PRのターゲットブランチ
   • Production branchへのPRのみプレビューが作成される
   • 例: feature/test → main (◯)
   • 例: bugfix/a → develop (✗)

問題5: wrangler deploy でエラー（Workers用コマンド）

エラー例:

✘ [ERROR] It looks like you've run a Workers-specific command in a Pages project.
  For Pages, please run `wrangler pages deploy` instead.

問題の原因:

wrangler deploy は Workers 用のコマンド。Pages プロジェクトでは wrangler pages deploy を使う必要がある。

解決策:

デプロイコマンドを修正：

# ❌ 間違い
npx wrangler deploy

# ✅ 正しい
npx wrangler pages deploy dist

実際の対応ログ（2025-12-07）:

Cloudflare Dashboard のデプロイコマンドを npx wrangler pages deploy dist に変更して解決。

問題6: 認証エラー（CLOUDFLARE_API_TOKEN）

エラー例:

✘ [ERROR] A request to the Cloudflare API failed.
  Authentication error [code: 10000]

📎 It looks like you are authenticating Wrangler via a custom API token set in an environment variable.
ℹ️  The API Token is read from the CLOUDFLARE_API_TOKEN environment variable.

問題の原因:

環境変数 CLOUDFLARE_API_TOKEN に設定されているトークンに Cloudflare Pages: Edit 権限がない。

解決策:

以下のいずれか：

1. CLOUDFLARE_API_TOKEN を削除（推奨）
   • Settings → Variables and secrets から削除
   • Git連携ではCloudflareが自動でトークンを提供する
2. トークンに権限を追加
   • https://dash.cloudflare.com/profile/api-tokens
   • 該当トークンを編集
   • Account → Cloudflare Pages → Edit を追加

実際の対応ログ（2025-12-07）:

APIトークンの権限設定で「Cloudflare Pages: 編集」を追加して解決。

問題7: ビルドトークンが無効

エラー例:

Failed: The build token selected for this build has been deleted or rolled and cannot be used for this build.
Please update your build token in the Worker Builds settings and retry the build.

問題の原因:

環境変数を変更した際に、以前使用していたビルドトークンが無効になった。

解決策:

Settings → API トークン で新しいトークンを選択または作成。

問題8: プロジェクトが見つからない

エラー例:

✘ [ERROR] A request to the Cloudflare API (/accounts/.../pages/projects/mdx-playground-web) failed.
  Project not found. The specified project name does not match any of your existing projects. [code: 8000007]

問題の原因:

wrangler.toml の name が古いプロジェクト名（削除済み）を指している。プロジェクトを削除して再作成した場合、プロジェクト名が変わっている可能性がある。

解決策:

以下のいずれか：

1. wrangler.toml を修正

   name = "新しいプロジェクト名"
   

2. デプロイコマンドで明示的に指定

   npx wrangler pages deploy dist --project-name=新しいプロジェクト名
   

実際の対応ログ（2025-12-07）:

デプロイコマンドを以下に変更して解決：

npx wrangler pages deploy dist --project-name=mdx-playground

しかし、最終的には true に変更することで解決（問題10参照）。

問題9: モノレポで .npmrc がルートにない

エラー例:

[error] Cannot find native binding.
Cannot find module '@oxc-parser/binding-linux-x64-gnu'

問題の原因:

モノレポ構成で pnpm-lock.yaml がルートにあるが、.npmrc（supportedArchitectures 設定）が apps/web/ にしかない。Cloudflare がルートで pnpm install を実行するため、設定が適用されない。

解決策:

ルートにも .npmrc を作成：

# リポジトリルート/.npmrc
supportedArchitectures.os=linux,win32,darwin
supportedArchitectures.cpu=x64,arm64

実際の対応ログ（2025-12-07）:

リポジトリルートに .npmrc を作成し、supportedArchitectures を設定して解決。

問題10: Git連携でwranglerを使うとデプロイが失敗する（最重要）

エラー例:

様々なエラーが発生：

• Authentication error [code: 10000]
• Project not found [code: 8000007]
• The build token has been deleted or rolled

問題の原因:

Git連携では wrangler コマンドは不要。 Cloudflareがビルド成果物を自動的にデプロイするため。

wranglerを使おうとすると：

1. APIトークンの権限問題
2. プロジェクト名の不一致
3. ビルドトークンの問題

などが連鎖的に発生する。

解決策:

デプロイコマンドを true に設定：

ビルドコマンド: pnpm install && pnpm generate
デプロイコマンド: true
ルートディレクトリ: apps/web

true はシェルで「何もしないで成功」を意味する。ビルドが完了すれば、Cloudflareが自動的に dist フォルダをデプロイする。

Direct Upload vs Git連携の違い:

実際の対応ログ（2025-12-07）:

デプロイコマンドを true に変更したところ、正常にデプロイが完了。

最終的な設定：

ビルドコマンド: pnpm install && pnpm generate
デプロイコマンド: true
ルートディレクトリ: apps/web
環境変数: NODE_VERSION=22

問題11: デプロイ成功後「Hello World」しか表示されない

エラー例:

ビルドは成功したが、サイトにアクセスすると：

Hello world

しか表示されず、コンテンツが見えない。

問題の原因:

ビルドコマンドに npm run build (nuxt build) を使用している。

• nuxt build = SSRモード（サーバーサイドレンダリング）
  • ランタイムでD1データベースからコンテンツを取得
  • D1にデータがないと空ページ表示
• nuxt generate = SSGモード（静的サイト生成）
  • ビルド時にすべてのコンテンツをHTMLに事前レンダリング
  • D1データベース不要

解決策:

ビルドコマンドを pnpm generate に変更：

# ❌ 間違い（SSRモード）
npm run build

# ✅ 正しい（静的サイト生成）
pnpm install && pnpm generate

なぜ「Hello world」が表示されるか:

1. SSRビルドでは、nuxt.config.ts の prerender.routes に指定されたルートのみ事前レンダリング
2. 他のコンテンツページ（/2025-11-28/... など）はランタイムでD1から取得
3. D1データベースにコンテンツがないため、空のページ（デフォルト表示）が返される

nuxt.config.ts の関連設定（問題箇所）:

nitro: {
  preset: "cloudflare-pages",
  prerender: {
    crawlLinks: true,
    routes: ['/blog', '/']  // ← これらのルートのみ事前レンダリング
  }
}

Direct Upload と Git連携の違い:

実際の対応ログ（2025-12-07）:

Cloudflare Dashboard のビルドコマンドを以下に変更：

pnpm install && pnpm generate

これにより、すべてのコンテンツページが事前レンダリングされ、正常に表示されるようになった。

チェックリスト

移行作業のチェックリストです。

移行前

• カスタムドメイン・サブドメインをメモ
• 環境変数をすべてメモ
• ビルド設定をメモ
• プロジェクト名をメモ
• 現在のサイトのスクリーンショットを保存
• GitHubに最新コードをpush

移行中

• 既存プロジェクトを削除
• Git連携で新規プロジェクト作成
• 同じプロジェクト名で作成（URLを維持する場合）
• ビルド設定を正しく入力
• 環境変数をすべて設定
• 初回デプロイ成功を確認

移行後

• カスタムドメインを再設定
• SSL証明書が有効化されているか確認
• サイトが正常に表示されるか確認
• テストコミットで自動デプロイを確認
• プレビューデプロイ（PR）の動作確認
• 古いデプロイURLをリダイレクト設定（必要に応じて）

移行後の運用フロー

通常の開発フロー

# 1. 機能ブランチを作成
git checkout -b feature/new-feature

# 2. コードを変更
# ... 編集 ...

# 3. コミット & プッシュ
git add .
git commit -m "Add new feature"
git push origin feature/new-feature

# 4. GitHubでPull Request作成
# → プレビューURLが自動生成される

# 5. レビュー & マージ
# → mainブランチに自動デプロイ

ホットフィックスの場合

# 1. mainから直接修正
git checkout main
git pull

# 2. 修正してプッシュ
git add .
git commit -m "Hotfix: critical bug"
git push

# → 即座に本番環境にデプロイされる

まとめ

移行のメリット

✅ 自動デプロイ

• GitHubにpushするだけで自動ビルド・デプロイ
• 手動コマンド実行が不要

✅ プレビューデプロイ

• Pull Request単位でプレビュー環境を自動作成
• レビュー時に実際の動作を確認可能

✅ デプロイ履歴

• ビルドログ、デプロイ履歴を一元管理
• ロールバックも簡単

✅ チーム開発

• 複数人での開発が容易
• PRベースのワークフローが使える

移行時の注意点

⚠️ プロジェクトの削除が必要（Direct Upload → Git連携は直接変更不可） ⚠️ カスタムドメイン・環境変数は手動で再設定 ⚠️ 初回設定を正しく行わないとビルドが失敗する

参考リンク

• Cloudflare Pages Git Integration
• GitHub Integration Guide
• Cloudflare Pages Builds
• Custom Domains

移行作業は慎重に行い、必ず設定のバックアップを取ってから実行してください。