Astro项目本地构建/开发报错：导入astro-icon失败，cheerio无default导出

嘿，我看到你在本地运行astro dev或astro build时遇到了这个棘手的报错，这大概率是依赖版本不兼容导致的问题，我帮你梳理下细节和解决办法：

环境信息 #

• 操作系统: Windows 10
• Node版本: v20.16.0
• 包管理器: Pnpm v9.7.0
• Astro版本: v4.13.1

具体报错内容 #

运行构建/开发命令时，Vite会抛出以下错误：

[vite] Error when evaluating SSR module F:\oceanh_workspace\Project\blog-astro\astro.config.mjs: failed to import "astro-icon"
|-file:///F:/oceanh_workspace/Project/blogastro/node_modules/.pnpm/@iconify+tools@3.0.7/node_modules/@iconify/tools/lib/svg/index.mjs:1
import cheerio from 'cheerio';
^^^^^^^
SyntaxError: The requested module 'cheerio' does not provide an export named 'default'
at ModuleJob._instantiate (node:internal/modules/esm/module_job:134:21)
at async ModuleJob.run (node:internal/modules/esm/module_job:217:5)
at async nodeImport (file:///F:/oceanh_workspace/Project/blog-astro/node_modules/.pnpm/vite@5.4.0_@types+no...

问题原因 #

报错的核心是@iconify/tools@3.0.7（astro-icon的依赖）试图使用import cheerio from 'cheerio'这种默认导入的方式，但新版cheerio已经移除了default导出，只提供命名导出，两者就产生了兼容性冲突。

可行的解决办法 #

你可以按照以下步骤尝试解决：

1. 强制锁定cheerio的兼容版本
   因为你用的是pnpm，可以在项目的package.json中添加pnpm.overrides配置，强制指定cheerio为支持默认导出的版本（比如1.0.0-rc.12）：

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

   配置完成后，运行pnpm install重新安装依赖，再尝试启动项目。

2. 升级astro-icon到最新版本
   检查astro-icon是否已经发布了适配新版cheerio的更新，运行以下命令升级：

   pnpm update astro-icon
   

   升级完成后重启项目，看报错是否消失。

3. 清理缓存后重新安装依赖
   有时候包管理器的缓存会导致依赖异常，你可以先清理pnpm缓存，再重新安装：

   # 清理pnpm缓存
   pnpm store prune
   # 删除node_modules和锁文件
   rm -rf node_modules pnpm-lock.yaml
   # 重新安装依赖
   pnpm install
   

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