CF Pages のビルド失敗？よくある 8 パターンと解決策で半日分のデバッグを節約

Cloudflare Pages のビルドログに、赤い「Failed」。今夜 5 回目の失敗で、明日の朝にはクライアントへのデモがあります。500 行近いログに npm ERR! が溢れ、どの行から見ればよいか分かりません。ネットの対処法を試しても効かないもの、状況を悪化させるものもありました。

CF Pages のビルド失敗の多くは、環境差・依存関係の設定・バージョン互換の 3 類型に収まります。この規則を押さえれば、90% は 10 分以内に解決できます。本記事では Pages のビルド環境を整理し、よくある 8 つの失敗シナリオ（実際のエラーと手順付き）と予防的な設定をまとめます。読み終えれば、切り分けの筋道がはっきりするはずです。

第 1 部：Cloudflare Pages のビルド環境を理解する

Pages ビルド環境の特殊性

具体的な問題に入る前に、一点だけ押さえてください。Cloudflare Pages のビルド環境は、ローカル開発環境と本質的に異なります。Pages のデプロイエラーは、コードの誤りではなく環境の違いであることが多いのです。

デフォルト設定は次のとおりです：

• OS：Ubuntu（Build System V2 は Ubuntu 22）
• Node バージョン：18.17.1（意外と古い）
• パッケージマネージャー：デフォルトは npm install ではなく npm clean-install
• ビルドタイムアウト：20 分のハードリミット
• Worker サイズ：10MB 上限

Node が古いのはなぜか — Cloudflare は安定性を優先しています。一方で多くの新パッケージは Node >= 18.18.0 や >= 20.0.0 を要求し、バージョン衝突が起きます。

ローカルとの 3 つの重要な差：

1. ファイルシステムの大文字小文字：Windows や Mac では import Header from './header' と書いてファイル名が Header.js でも動くことがあります。Linux では厳密に一致が必要です。見落としやすい落とし穴です。
2. ネットワーク：ローカルでは npm ミラー（淘宝源など）を使っていることがありますが、Pages は公式 npm に直結し、タイムアウトすることがあります。
3. デフォルトビルドコマンド：Cloudflare は build command の前に npm clean-install --progress=false を自動実行します。npm install より厳格で、package-lock.json と package.json がずれるとエラーになります。

問題を素早く切り分ける方法

環境の違いが分かったら、デプロイエラー時に真因をどう見つけるか。

ステップ 1：ビルドログを読む

ログは数百行になりますが、次の箇所だけ見れば十分です：

# 最後の ERR! または ERROR を探す
npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
# Vite/Webpack のエラー
[vite]: Rollup failed to resolve import
# Git 関連
fatal: unable to access repository

「ERR!」（感嘆符込み）で検索し、3〜5 行上を読むと原因にたどり着くことが多いです。インストール出力の前半に惑わされないでください。

ステップ 2：Deployment ID を保存する

ビルド失敗のたびに一意の Deployment ID が付きます。ブラウザのアドレスバー例：

https://dash.cloudflare.com/xxx/pages/view/your-project/a398d794-7322-4c97-96d9-40b5140a8d9b
                                                          ↑ Deployment ID

Cloudflare サポートやコミュニティで助けを求めるとき、この ID があればビルド記録を特定できます。

ステップ 3：ローカルで再現する

多くの人が飛ばすステップです。Linux 環境で再現してみてください：

# 方法 1：Docker で Ubuntu 22 を模擬
docker run -it ubuntu:22.04 bash
# 方法 2：Pages と同じ npm ci
npm ci
# 方法 3：nvm で Node を指定
nvm use 18.17.1

ローカルで npm ci が失敗すれば依存関係の問題。Node 18.17.1 で落ちればバージョン互換の問題です。

第 2 部：よくある 8 つのビルド失敗と解決策

問題 1：依存関係のインストール失敗（npm install エラー）

典型的なエラー：

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! Fix the upstream dependency conflict, or retry this command
npm ERR! with --force or --legacy-peer-deps
または
npm ERR! code ERR_SOCKET_TIMEOUT
npm ERR! network Socket timeout

いちばん多いパターンです。ローカルでは npm install が通るのに Pages で ERESOLVE — 理由は Cloudflare がデフォルトで npm ci を使うためです。

原因：

1. npm clean-install は peer dependency を自動解決しない
2. package-lock.json と package.json の不整合
3. ネットワークタイムアウト（公式 npm に届かない）

解決策（おすすめ順）：

方案 1：デフォルトインストールをスキップし、コマンドをカスタム

# Pages 設定で環境変数を追加
SKIP_DEPENDENCY_INSTALL=true
# Build command を変更
npm install --legacy-peer-deps && npm run build

いちばん直接的です。デフォルトのインストールは使わず、自分で依存関係を管理します。

方案 2：package-lock.json を修正

rm package-lock.json
npm install
git add package-lock.json
git commit -m "fix: regenerate package-lock.json"
git push

lock が壊れているだけのこともあります。再生成で直ることがあります。

方案 3：GitHub Actions でビルドを引き受ける

上記 2 つでダメなら、GitHub Actions + cloudflare/pages-action でビルド環境を完全にコントロールします。

# .github/workflows/deploy.yml
- name: Install dependencies
  run: npm install --force
- name: Build
  run: npm run build
- name: Deploy to Cloudflare Pages
  uses: cloudflare/pages-action@v1

予防：ローカルで定期的に npm ci を実行し、lock が同期していることを確認してください。

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

今すぐ始める →広告

問題 2：Node バージョン非互換

典型的なエラー：

ERR_PNPM_UNSUPPORTED_ENGINE Unsupported environment
This package requires Node.js version ^18.18.0 or >=20.0.0
または
The engine "node" is incompatible with this module.
Expected version ">=18.18.0". Got "18.17.1"

このエラーはほぼ Node が古すぎるサインです。TypeScript ESLint や Next.js 14+ は Node >= 18.18.0 を要求しますが、Pages デフォルトは 18.17.1 です。

解決策（いずれか 1 つで可）：

方案 1：環境変数（最推奨）

Cloudflare Pages の Settings > Environment variables に追加：

変数名: NODE_VERSION
値: 20.11.0

公式推奨のシンプルな方法です。

方案 2：.node-version ファイル

プロジェクトルートに作成：

echo "20.11.0" > .node-version
git add .node-version
git commit -m "chore: specify Node version for Cloudflare Pages"

方案 3：.nvmrc ファイル

ファイル名だけ異なり、内容は同様です：

echo "20.11.0" > .nvmrc

ベストプラクティス：環境変数と .node-version の両方を使い、ローカルと本番を揃えましょう。バージョンは最新より LTS（20.11.0 など）が無難です。

問題 3：ビルドタイムアウト（20 分超過）

典型的な症状：

ログがちょうど 20 分で止まり、明確なエラーはなく次の 1 行だけ：

Build exceeded maximum time of 20 minutes

情報がほぼなく、イライラしやすいパターンです。大規模プロジェクトや依存が多いときに起きがちです。

原因：

• 依存が多く npm install だけで 15 分かかる
• ビルドスクリプトの重複処理（毎回サイト全体を再生成など）
• ビルドキャッシュを活かしていない

解決策：

方案 1：ビルドキャッシュをクリア

キャッシュが逆に邪魔になることもあります。Pages 設定で：

Settings > Builds & deployments > Clear build cache

クリア後に再ビルドで直った経験は何度もあります。

方案 2：依存を分析・最適化

bundle analyzer で巨大な依存を特定：

npm install --save-dev @next/bundle-analyzer
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})
module.exports = withBundleAnalyzer({ /* 設定 */ })

ANALYZE=true npm run build を 1 回実行。moment.js 丸ごと import を day.js に替えてビルドが 3 分短縮した例もあります。

方案 3：一部タスクを CI に移す

typecheck や lint を GitHub Actions に移し、Pages はビルドのみ：

{
  "scripts": {
    "build": "next build",
    "build:full": "npm run typecheck && npm run lint && npm run build"
  }
}

方案 4：pnpm を使う

依存インストールが npm より速いことが多いです。Pages で：

Build command: pnpm install && pnpm run build

問題 4：モジュール解決エラー（Module not found）

典型的なエラー：

Module not found: Error: Can't resolve './App' in '/opt/buildhome/repo/src'
Did you mean 'App.js'?
または
[vite]: Rollup failed to resolve import '/src/components/Snackbar'
from '/opt/buildhome/repo/src/pages/Login.jsx'

非常に紛らわしいエラーです。ローカルでは動くのに Pages でモジュールが見つからない — 99% は大文字小文字です。

原因：

Linux は大文字小文字を厳密に区別し、Windows と macOS はデフォルトで区別しません。import App from './app' でファイルが App.js だと、Windows では通っても Linux ではエラーになります。

解決策：

方案 1：import パスをすべて修正

根本的な対処です。すべての import でファイル名と完全一致させます：

// ❌ 誤り
import Header from './header';  // ファイル名は Header.jsx
// ✅ 正しい
import Header from './Header';

手作業は大変なので、ESLint で自動検出を推奨します：

module.exports = {
  rules: {
    'import/no-unresolved': 'error',
  }
}

方案 2：パスエイリアス

絶対パスやエイリアスでミスを減らせます：

export default {
  resolve: {
    alias: {
      '@': '/src',
      '@components': '/src/components'
    }
  }
}
import Header from '@components/Header';

方案 3：コミュニティの「おまじない」

フォルダ名を一度別名にリネームしてコミットし、元に戻してコミットすると直る、という報告があります。キャッシュの可能性。他がダメなら試す価値はあります。

問題 5：環境変数の設定ミス

典型的な症状：

console.log(process.env.API_KEY); // undefined

またはビルド時に環境変数が見つからないエラー。

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

15%割引を入手 →広告

原因：

ビルド時とランタイムの環境変数を混同していることが多いです。フレームワークごとに命名規則も異なります。

押さえること：

Cloudflare Pages の環境変数は 2 種類です：

1. ビルド時変数：npm run build で使え、コードにコンパイルされる
2. ランタイム変数：Functions（エッジ関数）でのみ利用可能

静的サイト（純 HTML/JS）ではランタイム変数は使えず、ビルド時変数のみです。

解決策：

方案 1：変数の種類を正しく設定

Pages 設定で変数を追加するとき：

• 「Production」「Preview」の環境を選択
• ビルド時に必要なら「Build」に必ずチェック

方案 2：フレームワークの命名規則

# Vite：VITE_ で始める
VITE_API_KEY=xxx
# Next.js 公開変数：NEXT_PUBLIC_
NEXT_PUBLIC_API_KEY=xxx
# Nuxt：nuxt.config.js の runtimeConfig

方案 3：機密情報は Secret 型

Pages には Text（値が見える）と Secret（暗号化）があります。API キーや DB パスワードは Secret を使ってください。

ベストプラクティス：

1. ローカルは .env.local（.gitignore に追加）
2. 本番は Pages の環境変数
3. Preview はテスト API、Production は本番 API と環境ごとに分ける

問題 6：Git 連携の問題

典型的な症状：

• リポジトリへのアクセスを認可できない
• 「This repository is already in use by another Pages project」
• Push しても Pages が自動ビルドしない

原因：

GitHub/GitLab の認可問題、または Cloudflare の制限（同一リポジトリを複数アカウントで使えない）が多いです。

解決策：

方案 1：GitHub App を再認可

GitHub の Settings > Applications > Cloudflare Pages > Configure > Uninstall のあと、Cloudflare Dashboard でリポジトリを再接続すると再認可が走ります。

方案 2：リポジトリの使用状況を確認

「既に使用中」なら、複数の Cloudflare アカウントで同じリポを使っていないか確認してください。他アカウントの Pages プロジェクトを削除する必要があります。

方案 3：GitHub の権限

連携にはリポジトリで Maintainer 以上が必要です。Contributor だけでは接続できません。

方案 4：特殊文字を避ける

コミットメッセージに絵文字や特殊文字を入れると、ビルドトリガーが失敗することがあります。GitHub は許可しても Cloudflare が正しく解釈しない場合があります。

既知の制限：フォークしたリポジトリの PR ではプレビューデプロイが走りません。将来対応予定ですが、現時点では未対応です。

問題 7：Functions のデプロイ失敗

典型的な症状：

ビルドは成功するが最終デプロイで失敗し、ログに有用な情報が少ない。または：

Build failed: Functions bundle size exceeding limit

原因：

• Worker バンドルが 10MB を超過
• Functions の Bindings（KV、D1、R2）の誤設定
• エッジで使えない Node.js 専用 API の使用

解決策：

方案 1：Functions バンドルサイズを分析

bundle analyzer で何が大きいか確認。tree-shaking されずライブラリ全体が入っていることが多いです。

方案 2：Astro/SvelteKit の adapter 設定

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

Astro はデフォルトでプリレンダー済みページも Functions に入り、サイズが膨らむことがあります。mode: 'directory' で改善できます。

方案 3：Bindings の確認

Settings > Functions > Bindings

コードで使う KV、D1、R2 が正しく紐づいているか確認してください。

方案 4：Node.js 専用 API を避ける

Workers は V8 環境で、完全な Node.js ではありません。使えない例：

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

今すぐ始める →広告

• fs
• path（一部非対応）
• child_process
• net / http（fetch を使う）

必要ならビルド時に処理する設計に切り替えてください。

問題 8：キャッシュとカスタムドメインの問題

典型的な症状：

• デプロイ成功だがサイトが古い内容のまま
• カスタムドメインは 404、.pages.dev は正常
• トップが 404 Not Found

原因：

• Page Rules が Pages のキャッシュと干渉
• カスタムドメインの DNS 誤設定
• index.html がない

解決策：

方案 1：Cache Everything の Page Rule を削除

カスタムドメインが Proxied（オレンジの雲）なら Zone 設定が Pages に影響します。Rules > Page Rules で「Cache Everything」があれば削除。Pages には独自のキャッシュがあり、Page Rule は不要です。

方案 2：カスタムドメインを DNS Only に

効かない場合、DNS レコードを灰色の雲（DNS Only）に変更し、プロキシをバイパスして Pages に直結させてみてください。

方案 3：index.html の存在を確認

yourdomain.com/ が 404 なら、ビルド出力に index.html があるか確認。多くのフレームワークは dist/index.html など — Pages の「Build output directory」が正しいかも見てください。

方案 4：キャッシュを手動パージ

Caching > Configuration > Purge Everything

Zone 全体のキャッシュが消えるので、慎重に使ってください。

第 3 部：予防のベストプラクティス

ビルド設定のベストプラクティス

問題が出てから直すより、最初から整えておく方が楽です。

1. Node バージョンを明示

デフォルトに頼らず、明示的に指定：

# .node-version
20.11.0
# Pages の環境変数でも
NODE_VERSION=20.11.0

2. ブランチごとにビルドコマンドを分ける

CF_PAGES_BRANCH を利用：

{
  "scripts": {
    "build": "node scripts/build.js",
    "build:production": "next build",
    "build:preview": "next build && next export"
  }
}

const branch = process.env.CF_PAGES_BRANCH || 'main';
const command = branch === 'main' ? 'build:production' : 'build:preview';

3. monorepo ではルートディレクトリを指定

pnpm workspace や Turborepo では Pages で Root directory を指定：

Root directory: apps/web
Build command: pnpm run build

継続的な監視とデバッグ

1. ローカルデバッグ環境

Docker で Pages 環境を模擬：

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y nodejs npm
RUN node -v
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

2. Cloudflare Status を確認

奇妙なエラー時はまず https://www.cloudflarestatus.com/ を確認。Pages 側の障害なら待つのが正解です。

3. いつ Cloudflare サポートに連絡するか

すべて試してもダメ、プラットフォームのバグを疑う、ビルド制限の引き上げ（有料プラン）が必要 — そのときは Deployment ID と詳細ログを添えて連絡してください。

まとめ

CF Pages のビルド失敗は、大きく分けて数類型に収まります。90% は環境差（Node バージョン、ファイル名の大文字小文字）、依存関係（package-lock.json、peer dependency）、Pages の仕組みの誤解（環境変数、キャッシュ）のいずれかです。

体系的な切り分けが重要です：

1. ビルドログで本当のエラーを見つける
2. 依存・バージョン・パス・設定のどれか判断する
3. ローカルで再現する
4. 対応する解決策を当てはめる
5. 予防設定で再発を防ぐ

この記事をブックマークしておけば、次にビルドが落ちたときも 10 分以内に直せる可能性が高いです。緑の「✓ Deployed」が出たときの安堵感は、一度味わうと忘れられません。

他に Cloudflare Pages で困ったことがあれば、コメントで共有してください。誰かの助けになるかもしれません。