一、问题现象
项目技术栈：Vite + Vue + pnpm + @koi/core
启动项目时报错，Vite 无法解析 spark-md5 模块，完整报错信息如下：
[plugin:vite:import-analysis] Failed to resolve import "spark-md5" from "node_modules/.vite/deps/@koi_core.js". Does the file exist?最让人疑惑的问题：
-
执行
pnpm install修复无效，报错依旧； -
必须手动执行
pnpm add spark-md5才能安装依赖； -
安装依赖后不清理缓存，报错仍然存在。
二、根本原因：幽灵依赖（核心知识点）
1. 什么是幽灵依赖？
幽灵依赖（Phantom Dependency） ：第三方库代码中引入了某个依赖包，但该库的 package.json 中并未声明这个依赖。
本次场景：@koi/core 源码中使用了 import spark-md5，但是其内部依赖列表缺失spark-md5，属于库本身的打包缺陷。
2. 为什么 npm 能跑，pnpm 直接报错？
这是 pnpm 和 npm 核心机制的区别，也是本次报错的关键：
-
npm/yarn（宽松模式） ：会扁平化
node_modules，所有依赖提升到顶层，即使子包未声明依赖，只要项目有对应包，就能侥幸运行； -
pnpm（严格隔离模式） ：强依赖隔离机制，每个包只能读取自身package.json声明的依赖，不会自动扫描源码、不会补全幽灵依赖。
3. 重点：pnpm install 为什么无效？
很多前端开发者都会混淆这两个命令，这里彻底讲清楚：
-
pnpm install：只还原现有依赖 ，仅安装项目package.json中已写入的包，不会新增任何依赖； -
pnpm add xxx：新增并安装依赖，将包写入项目依赖列表，同时下载到本地，全局可解析。
简单来说：幽灵依赖属于未声明的隐性依赖，install 不会自动补全，只能手动 add。
三、完整解决方案（100%生效）
很多人安装依赖后依旧报错，是因为漏掉了 清理Vite预构建缓存 关键步骤！
步骤1：手动安装缺失的幽灵依赖
# 安装核心依赖
pnpm add spark-md5
# 如需TS类型支持，执行这句
pnpm add -D @types/spark-md5步骤2：清理Vite缓存（必做）
Vite 会将第三方依赖预构建并缓存到 .vite 文件夹，旧缓存会持续报错，必须删除：
# Mac/Linux 清理缓存
rm -rf node_modules/.vite
# Windows PowerShell 清理缓存
Remove-Item -Recurse -Force node_modules\.vite步骤3：重启项目
pnpm dev至此，报错彻底解决。
四、备选兜底方案（不推荐单独使用）
可以通过配置 pnpm 规则忽略缺失依赖警告，在项目根目录 package.json 中添加以下配置：
{
"pnpm": {
"peerDependencyRules": {
"ignoreMissing": ["spark-md5"]
}
}
}重要提醒 ：该配置仅让 pnpm 不抛出警告，不会自动下载安装依赖，Vite 依旧会模块解析失败！仅可作为辅助配置，不能替代 add 安装命令。
五、问题溯源：到底是谁的Bug？
本次报错非项目代码问题、非pnpm配置问题 ，根源是 @koi/core 库的打包漏洞：
库作者在源码中使用了 spark-md5 实现文件MD5哈希校验（上传组件核心功能），但发布时未在 package.json 声明该依赖，导致 pnpm 严格模式下直接报错，npm 宽松模式侥幸兼容。
六、前端通用避坑总结
通过本次踩坑，总结 pnpm + Vite 项目通用排错技巧：
- pnpm 严格依赖隔离，会暴露所有第三方库的幽灵依赖漏洞，npm能跑不代表代码规范；
七、最终总结
spark-md5 模块解析失败的核心：@koi/core 存在幽灵依赖 + pnpm严格依赖机制。
pnpm install 只能还原已有依赖，无法补全未声明的幽灵依赖，因此必须手动执行 pnpm add 安装，搭配清理Vite缓存、重启服务即可完美解决。
原创不易，如有帮助欢迎点赞、收藏、关注！持续更新前端踩坑干货✨