调试 Pages

设置 Pages 项目时，你可能会遇到各种阻止成功部署的错误。本指南概述一些常见错误及解决方案。

你可以在 Pages 构建日志中查看构建错误。要访问构建日志：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Pages 项目。

3. 前往 Deployments（部署） > View details（查看详情） > Build log。

以下各节包含构建日志中可能出现的错误。

此步骤的错误可能由 Git 集成安装不当引起。

在 GitHub 中修复：

1. 登录 GitHub 账户。
2. 从用户图标进入 Settings（设置） > 在 Integrations（集成） 下找到 Applications（应用程序）。
3. 找到 Cloudflare Pages > Configure（配置） > 向下滚动并选择 Uninstall（卸载）。
4. 在 Cloudflare 仪表板中重新授权 GitHub 用户/组织。

在 GitLab 中修复：

1. 登录 GitLab 账户。
2. 从用户图标进入 Preferences（偏好设置） > Applications（应用程序）。
3. 找到 Cloudflare Pages > 向下滚动并选择 Revoke（撤销）。

请注意，你需要 Maintainer 或更高权限才能成功关联仓库，否则构建将失败。

此步骤的错误可能由缺少 Git Large File Storage (LFS) 引起。请参阅 GitHub ↗ 和 GitLab ↗ 文档检查 LFS 使用情况。

同时请检查根目录 .gitmodules 文件中的 submodule 配置。该文件需同时包含 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 项目设置不当引起。请检查构建命令、输出文件夹和环境变量是否存在错误配置。

此步骤的错误可能由 Pages Functions 配置不正确引起。有关 Functions 设置，请参阅 Functions 文档。

若未使用 Functions，或已确认 Functions 配置无错误，请查看 Cloudflare 状态站点 ↗ 是否存在导致构建失败的 Cloudflare 网络问题。

若自定义域通过 Cloudflare 代理（橙色云），zone 的设置（如缓存）将生效。

若新内容未显示，请在 Cloudflare 仪表板中前往 Rules（规则） > Page Rules（页面规则），检查是否存在启用了 Cache Everything（全部缓存） 的 Page Rule。若存在，请移除此规则，因为 Pages 自行管理缓存。

若自定义域出现错误而 pages.dev 域正常，请在 Cloudflare 仪表板中前往 DNS > Records（记录），将项目的 DNS 记录设置为 DNS Only（灰色云）。若错误仍然存在，请检查 zone 配置。

若 自定义域 在 Cloudflare 仪表板中一直停留在 Verifying（验证中） 阶段，请参阅以下调试步骤。

Pages 使用 HTTP 验证，验证期间需要访问 HTTP 端点。若有其他 Cloudflare 产品挡在前面（如 Access、重定向、Worker 等），验证将无法完成。

要检查此问题，请对域名运行 curl 命令，访问 /.well-known/acme-challenge/randomstring。例如：

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

在上例中，请求被重定向到 Cloudflare Access（如 Location 标头所示）。此时需要在域名验证完成前在域上禁用 Access。验证完成后可重新启用 Access。

对 Redirect Rules 或 Worker 也需要进行类似处理。

更多详情，请参阅 排查域名控制验证 (DCV) 文章。

若 HTTP 验证未被阻止，可能缺少 Certification Authority Authorization (CAA) 记录。若已禁用 Universal SSL 或使用外部提供商，则很可能出现此情况。

要检查此问题，请对自定义域 apex（或 子域 zone 的 zone）运行 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

上例中仅有一条 CAA 记录，允许 Amazon 签发证书。

要解决此问题，需添加以下 CAA 记录，允许 Cloudflare 使用的所有证书颁发机构 (CA) 签发证书：

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 为处于区域冻结下的主机名添加自定义域。

要为处于区域冻结的主机名添加自定义域，请在自定义域设置过程中临时 解除区域冻结。

自定义域成功完成后，可以 重新启用 zone hold。

若在根 pages.dev URL（example.pages.dev）上看到 404 错误，可能是项目中缺少 index.html 文件。

上传 index.html 文件即可解决此问题。

若需要更多构建错误排查指导，Enterprise 客户可联系 Cloudflare 账户团队，或参阅 支持中心 了解如何联系 Cloudflare 支持。

你也可以在 Cloudflare Developers Discord ↗ 的 Pages 版块提问。