Pages のデバッグ

Pages プロジェクトのセットアップ中に、サイトのデプロイを妨げるエラーが出ることがあります。このガイドでは、よくあるエラーと対処方法を説明します。

ビルドログを確認する

ビルドエラーは Pages のビルドログで確認できます。ビルドログを開く手順は次のとおりです。

Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗
Pages プロジェクトを選びます。
Deployments > View details > Build log を開きます。

Cloudflare ダッシュボードにログインしたあと、上記の手順でビルドログを開きます

ビルドログに出る可能性のあるエラーは、以降のセクションにあります。

ビルド環境の初期化

このステップのエラーは、Git 連携時のインストール不備が原因になることがあります。

GitHub で直す手順は次のとおりです。

GitHub アカウントにログインします。
ユーザーアイコンから Settings を開き、Integrations の Applications を探します。
Cloudflare Pages を見つけ、Configure を選び、下へスクロールして Uninstall を選びます。
Cloudflare ダッシュボードで、GitHub のユーザーまたは Organization を再認可します。

GitLab で直す手順は次のとおりです。

GitLab アカウントにログインします。
ユーザーアイコンから Preferences > Applications を開きます。
Cloudflare Pages を見つけ、下へスクロールして Revoke を選びます。

リポジトリを正しく連携するには Maintainer 以上のロールが必要です。それ以外だとビルドは失敗します。

Git リポジトリのクローン

このステップのエラーは、Git Large File Storage (LFS) が使えないことが原因になることがあります。LFS の利用状況は GitHub ↗ と GitLab ↗ のドキュメントで確認してください。

ルートディレクトリの .gitmodules ファイルで、サブモジュール設定も確認してください。このファイルには path と url の両方が必要です。

正しい設定の例:

[submodule "example"]
	path = example/path
	url = git://github.com/example/repo.git

正しくない設定の例:

[submodule "example"]
	path = example/path

または

[submodule "example"]
        url = git://github.com/example/repo.git

アプリケーションのビルド

このステップのエラーは、Pages プロジェクトの設定不備が原因になることがあります。ビルドコマンド、出力フォルダー、環境変数に誤りがないか確認してください。

Cloudflare のグローバルネットワークへのデプロイ

このステップのエラーは、Pages Functions の設定誤りが原因になることがあります。Functions のセットアップは Functions のドキュメントを参照してください。

Functions を使っていない場合、または Functions の設定に問題がないことを確認した場合は、Cloudflare Status サイト ↗ で、ビルド失敗の原因になりうるネットワーク障害を確認してください。

`pages.dev` とカスタムドメインの違い

カスタムドメインが Cloudflare でプロキシされている場合（オレンジクラウド）、ゾーンのキャッシュなどの設定が適用されます。

新しいコンテンツが表示されない場合は、Cloudflare ダッシュボードの Rules > Page Rules を開き、Cache Everything が有効な Page Rule がないか確認します。ある場合は削除してください。Pages は独自にキャッシュを扱います。

カスタムドメインではエラーになるが pages.dev ドメインでは問題ない場合は、Cloudflare ダッシュボードの DNS > Records を開き、プロジェクトの DNS レコードを DNS Only（グレークラウド）にします。エラーが続く場合は、ゾーンの設定を確認してください。

ドメインが検証から進まない

カスタムドメインが Cloudflare ダッシュボードの Verifying のまま進まない場合は、次のデバッグ手順を参照してください。

HTTP 検証がブロックされている

Pages は HTTP 検証を使い、検証中に HTTP エンドポイントへ到達する必要があります。Access、リダイレクト、Worker など、別の Cloudflare 製品が途中にあると、検証を完了できません。

確認するには、ドメインの /.well-known/acme-challenge/randomstring に対して curl を実行します。例:

curl -s -o /dev/null -D - https://example.com/.well-known/acme-challenge/randomstring


HTTP/2 302
date: Mon, 03 Apr 2023 08:37:39 GMT
location: https://example.cloudflareaccess.com/cdn-cgi/access/login/example.com?kid=...&redirect_url=%2F.well-known%2Facme-challenge%2F...
access-control-allow-credentials: true
cache-control: private, max-age=0, no-store, no-cache, must-revalidate, post-check=0, pre-check=0
server: cloudflare
cf-ray: 7b1ffdaa8ad60693-MAN

上の例では、Location ヘッダーが示すとおり Cloudflare Access へリダイレクトしています。この場合、ドメインが検証されるまで、そのドメインの Access を無効にします。検証後に Access を再度有効にできます。

Redirect Rules や Worker でも、同様の対応が必要です。

詳細はドメイン管理の検証（DCV）のトラブルシューティングを参照してください。

CAA レコードがない

HTTP 検証をブロックしているものがなければ、Certification Authority Authorization (CAA) レコードが足りない可能性があります。Universal SSL を無効にしている場合や、外部プロバイダーを使っている場合に起きやすいです。

確認するには、カスタムドメインの apex（サブドメインゾーンの場合はゾーン）に対して dig を実行します。例:

dig CAA example.com


; <<>> DiG 9.10.6 <<>> CAA example.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 59018
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;example.com.		IN	CAA

;; ANSWER SECTION:
example.com.	300	IN	CAA	0 issue "amazon.com"

;; Query time: 92 msec
;; SERVER: 127.0.2.2#53(127.0.2.2)
;; WHEN: Mon Apr 03 10:15:51 BST 2023
;; MSG SIZE  rcvd: 76

上の例では、Amazon に証明書発行を許可する CAA レコードが 1 件だけあります。

対処するには、Cloudflare が使うすべての Certificate Authority (CA) が証明書を発行できるように、次の CAA レコードを追加します。

example.com.            300     IN      CAA     0 issue "letsencrypt.org"
example.com.            300     IN      CAA     0 issue "pki.goog; cansignhttpexchanges=yes"
example.com.            300     IN      CAA     0 issue "ssl.com"
example.com.            300     IN      CAA     0 issuewild "letsencrypt.org"
example.com.            300     IN      CAA     0 issuewild "pki.goog; cansignhttpexchanges=yes"
example.com.            300     IN      CAA     0 issuewild "ssl.com"

ゾーンホールド

ゾーンホールドがあると、ホールド対象のホスト名に Pages がカスタムドメインを追加できません。

ゾーンホールドがあるホスト名にカスタムドメインを追加するには、カスタムドメインのセットアップ中に一時的にゾーンホールドを解除します。

カスタムドメインの追加が完了したら、ゾーンホールドを再度有効にできます。

ルートの `pages.dev` URL に `index.html` がない

ルートの pages.dev URL（example.pages.dev）で 404 エラーになる場合は、プロジェクトに index.html ファイルがないことが多いです。

index.html ファイルをアップロードすると解決します。