Astro项目部署Cloudflare Pages时构建失败：astro-icon导入错误及cheerio导出异常

嘿，我太懂这种之前好好的项目突然构建报错的烦躁了！先给你拆解下问题根源：你看到的SyntaxError: The requested module 'cheerio' does not provide an export named 'default'，本质是cheerio新版本（v2.x及以上）移除了默认导出，但astro-icon依赖的@iconify/tools@3.0.7还在使用旧的默认导入写法（import cheerio from 'cheerio'），两者版本不兼容导致的。

下面给你几个可行的解决步骤，按顺序来就行：

方案一：锁定cheerio的兼容版本 #

通过包管理器的依赖覆盖功能，强制让@iconify/tools使用支持默认导出的cheerio v1.x系列版本：

• 如果你用pnpm，在package.json里添加：

  "pnpm": {
    "overrides": {
      "cheerio": "^1.0.0-rc.12"
    }
  }
  

• 如果你用npm，直接在package.json里加：

  "overrides": {
    "cheerio": "^1.0.0-rc.12"
  }
  

方案二：清理依赖重新安装 #

修改完配置后，清理旧的依赖和锁文件，确保新的依赖规则生效：

# 删除旧依赖和锁文件
rm -rf node_modules pnpm-lock.yaml # npm用户替换成package-lock.json
# 重新安装依赖
pnpm install # npm用户替换成npm install

方案三：本地预构建验证 #

先在本地跑一遍构建命令，确认报错已经消失：

npm run build # 或者pnpm build

没问题之后再推送到Cloudflare Pages，就能避免部署时再踩坑啦。

补充一句：之前正常现在突然出问题，大概率是Cloudflare Pages构建时拉取了最新依赖（如果你的锁文件没提交到仓库，或者依赖范围写得太宽），导致cheerio被自动升级到了不兼容版本。锁定版本后就能彻底解决这个问题了。

备注：内容来源于stack exchange，提问作者ZiaW