Cloudflare Pages API 上传失败？手把手教你排查原因并解决

最近在折腾 Cloudflare Pages 自动化部署的时候，遇到了一个挺让人头秃的问题：明明代码已经推上去，日志显示构建成功，但打开域名却是一片空白或者直接 404。最奇怪的是，如果我用 Cloudflare 的控制台手动上传文件，一切又正常了。

这种“由于 API 导致的玄学 Bug”其实并不少见。如果你也在用 GitHub Actions 或者其他 CI/CD 工具调用 Cloudflare API 部署 Pages 却踩了坑，不妨对照下面几个核心原因来排查一下，大概率能找到灵感。

为什么手动上传行，API 上传却不行？

首先我们要明白，手动上传和 API 创建部署在 Cloudflare 后端的处理逻辑上其实有些许差异。

Cloudflare Pages 构建配置设置界面示意图

在 Cloudflare Pages 设置中检查构建命令和输出目录，避免对纯静态文件进行不必要的构建。

手动上传时，Cloudflare 通常会将你上传的静态文件直接托管，相当于绕过了复杂的构建过程。而当你使用 API（或者 Git 集成）时，Cloudflare 默认会尝试寻找构建配置，比如 package.json、wrangler.toml 或者你在后台设置好的构建命令。

如果在这个过程中任何一个环节配置不对，虽然 API 返回了“接受”的状态，但实际上最终的产物是空的，自然就访问不了了。

排查第一步：检查构建配置是否被意外触发

很多时候，我们上传的是一个已经打包好的 dist 文件夹。这时候如果 Cloudflare 还在傻傻地执行 npm run build，那必然出问题。

Cloudflare Pages 部署日志界面示意图

查看实时的部署日志，确认构建状态、输出路径以及是否存在权限错误。

解决方案： 如果你上传的是纯静态文件（不需要构建），请务必在调用 API 创建部署时，或者在 Cloudflare Pages 的项目设置中，将构建命令留空，并将输出目录设置为 . （根目录）或者你对应的文件夹。

在使用 API 时，可以在请求体中明确指定：

{
  "source": { ... },
  "build_config": {
    "build_command": null,
    "destination_dir": "."
  }
}

确保没有多余的构建步骤破坏了你的文件结构。

排查第二步：环境变量缺失

如果你的项目确实需要构建，那么本地跑得好好的代码一到 API 上就挂，很可能是环境变量没传过去。

在手动上传或者 Git 关联模式下，我们经常会在后台 UI 里配置 API_KEY、DATABASE_URL 等变量。但在通过 API 触发部署时，这些变量如果没在请求参数中显式传递，构建过程就会因为缺少关键配置而失败，或者生成了错误的静态页。

解决方案： 确保你的 API 调用中包含了环境变量字段 env_vars，或者在 Cloudflare 后台为该特定的环境设置了正确的持续环境变量。

排查第三步：部署别名与路由问题

有时候构建其实成功了，文件也在那，但你访问的 URL 不对。

当你通过 API 创建新部署时，Cloudflare 默认可能不会自动将其分配到你的自定义域名上，而是分配了一个临动的 *.pages.dev 地址。如果这个新deployment 没有被正确设置为 Production 环境，你访问主域名时，实际上看到的还是旧的版本。

解决方案： 在 API 调用结束后，检查返回的 Deployment ID，并确认它是否已经成为了当前项目的“生产环境”别名。你可以通过 API 单独发起一个别名的设置请求，将你的自定义域名指向这个最新的部署 ID。

排查第四步：文件结构是否扁平

这是一个很低级但极其容易踩坑的点。

手动上传时，我们习惯选中文件夹。但在 API 上传（例如 Direct Upload 创建部署）时，如果你上传的压缩包解压后，最外层又包裹了一层文件夹名，Cloudflare 的路由匹配就会失效。

例如，你的静态文件应该在根目录下直接有 index.html，但上传包里是 project-v1.0/index.html。这种情况下，访问根目录就会 404。

终极调试手段：查看实时日志

不要只盯着 HTTP 状态码看。既然手动上传可以访问，说明域名没被封，也没被封 DNS 污染。那肯定就是云端构建或文件分发出了岔子。

进入 Cloudflare Dashboard -> Pages -> 选择你的项目 -> 查看 Deployments 列表。找到你通过 API 上传的那一条记录（通常会标记为 API 触发），点击进去看 Build logs。

这里会详细告诉你：

构建是否真的成功？
输出文件在哪里？
是否有 Permission Denied 错误？

总结

遇到“API 上传不行，手动上传可以”的问题，核心思路就是：假设 Cloudflare 也是个大傻瓜，它可能误解了你的意图。

别让它乱构建：如果是静态文件，清空构建配置。
别让它缺东西：补全环境变量。
别让它迷路：检查文件层级是否扁平，确保路由指向了最新的 Deployment。

希望这篇文章能帮你省下几个宝贵的头发，如果还有其他奇怪的现象，欢迎随时交流，毕竟在云原生的世界里，填坑也是一种乐趣！