pnpm与npm混用为什么会报错？

项目使用pnpm安装包和组件，使用npm打包时会报错，是为什么？

这是一个非常常见的问题。简单来说，pnpm 和 npm 处理依赖的方式（目录结构）完全不同，导致混用时会出现"找不到模块"或"依赖缺失"的错误。

以下是详细的原因分析和解决方案：

pnpm 的机制（硬链接 + 符号链接）：
- pnpm 为了节省磁盘空间，将所有包存储在一个全局的内容寻址存储区（store）中。
- 项目的 node_modules 中并不是真实的包文件，而是指向全局 store 的硬链接 和符号链接。
- pnpm 严格遵循 package.json 中声明的依赖关系。如果某个包没有在 dependencies 或 devDependencies 中显式声明，即使它被其他包依赖了，你在代码中也无法直接引用它 （因为 node_modules 里没有它的直接链接）。这被称为"幽灵依赖"（Phantom Dependencies）防护。
npm 的机制（扁平化/嵌套）：
- npm (v3+) 会将依赖尽可能扁平化 地安装在 node_modules 根目录下。
- 如果 A 依赖 B，B 依赖 C，npm 通常会把 C 也提升到根目录。这意味着即使你的 package.json 没写 C，你也能在代码里 import 'C'。
- 当你在 pnpm 安装的项目中运行 npm run build 时，npm 会尝试读取 node_modules。由于 pnpm 创建的符号链接结构不符合 npm 的预期（或者 npm 无法正确解析这些非扁平化的链接），或者因为 pnpm 隐藏了某些隐式依赖，打包工具（如 Webpack, Vite, Rollup）就无法找到所需的模块，从而报错。

这是最稳定、最推荐的方案。既然项目是用 pnpm 安装的，所有的脚本（install, build, dev, test）都应该用 pnpm 执行。

操作： 将构建命令从 npm run build 改为 pnpm run build。
CI/CD 调整： 如果你的项目在 GitHub Actions、GitLab CI 或 Jenkins 上运行，确保环境安装了 pnpm，并且运行的是 pnpm install 和 pnpm build。

如果你受限于某些旧的生产环境或特定的 Docker 镜像，只能使用 npm，你需要执行以下步骤来"清洗"环境：

删除现有的 node_modules 和锁文件： pnpm 生成的 node_modules 结构和 pnpm-lock.yaml 对 npm 是无效甚至有害的。
复制代码
```
rm -rf node_modules pnpm-lock.yaml
```
使用 npm 重新安装依赖： 让 npm 根据 package.json 生成它自己的 node_modules 结构和 package-lock.json。
复制代码
```
npm install
```
修复潜在的"幽灵依赖"问题： 由于 npm 会提升依赖，而 pnpm 不会，之前可能在 pnpm 下能跑通（因为配置了 .npmrc 或其他设置允许隐式依赖，或者刚好链路连通），但在纯 npm 环境下，如果代码里引用了未声明的包，可能会报错。
- 如果报错 Cannot find module 'xxx'，请检查代码，确保所有 import 的包都已在 package.json 的 dependencies 或 devDependencies 中显式声明。如果没有，手动安装：
  复制代码
```
npm install xxx
```
执行打包：
复制代码
```
npm run build
```

有些时候，你希望保留 pnpm 的安装方式，但让打包工具能识别更多依赖。可以在项目根目录创建或修改 .npmrc 文件，添加以下配置（但这通常不能解决根本的结构差异问题，主要用于开发体验）：

复制代码

# 允许提升依赖到 node_modules 根目录（类似 npm 的行为，但这会失去 pnpm 的严格性）
shamefully-hoist=true

注意：开启 shamefully-hoist=true 后，pnpm 的行为会变得像 npm 一样扁平化，虽然可能解决报错，但失去了 pnpm 防止幽灵依赖的核心优势，且可能导致构建体积变大。

结论： 报错的根本原因是工具链不匹配 。最正确的做法是**"谁安装，谁打包"**。如果是 pnpm 安装的，请务必用 pnpm 进行打包。