问题排查实战：Cloudflare Pages 构建失败我是如何定位并修复的

问题现象

今天发布博客时，Cloudflare Pages 显示构建失败。失败阶段在：

  • Cloning repository：通过
  • Installing dependencies：通过
  • Building application：失败

错误关键词：

  • Node.js v20.20.0 is not supported by Astro
  • Please upgrade Node.js to a supported version: ">=22.12.0"

影响范围

  • 新文章无法上线
  • 页面仍停留在上一版
  • 自动部署链路中断

排查路径

我按“先环境、后依赖、再配置”的顺序排查：

  1. 看构建日志中的实际 Node 版本
  2. 对照 package.json 中的 engines.node
  3. 检查 Cloudflare Pages 的环境变量配置
  4. 确认部署的 commit 是否是最新提交

根因分析

根因有两个：

  1. 云端构建 Node 版本和依赖要求不一致

    • 实际 Node：20.20.0
    • Astro 要求：>=22.12.0

  2. 触发了旧提交的重试，而不是最新提交的重新部署

    • 页面显示 HEAD 停在旧 commit

修复动作

我执行了以下修复：

  1. 在 Cloudflare Pages 构建环境中设置：
    • NODE_VERSION=22.12.0（或更高 22.x）
  2. 确保重新部署的是最新 commit
  3. 本地先执行：
npm run build
  1. 再提交并推送，触发自动部署

验证结果

  • 构建日志显示 Build complete
  • 线上首页可访问
  • 文章列表和新增文章页可正常打开

复盘与经验

这次排查让我确认了三条原则：

  1. 不要只看“失败”，要看失败在流水线的哪一步
  2. 环境版本冲突是最常见原因之一
  3. 每次修复后，必须确认部署的是“最新提交”

复用模板（可直接替换）

你可以把下面结构直接复制到后续故障复盘文章中：

  1. 问题现象（报错与阶段）
  2. 影响范围（影响了什么）
  3. 排查路径（按什么顺序查）
  4. 根因分析（最终结论）
  5. 修复动作（做了什么）
  6. 验证结果（如何确认修好）
  7. 经验沉淀（以后怎么避免）