新同事入职第一天拿着公司前端仓库的代码开始搭建环境pnpm install跑了大概几十秒正准备启动项目结果终端直接甩出一行红字Error: Cannot resolve lodash from src/utils/format.js问了一圈老员工用 npm 跑同一个项目完全没问题新同事自己在家用 pnpm 也是好好的。一时间大家都很懵同一个仓库、同一个 Node 环境为什么换了个包管理器就解析不到 lodash 了这不是个别现象。最近团队里陆续有人从 npm 切到 pnpm几乎都遇到过一类问题包明明在node_modules里能看到构建时却提示Cannot resolve xxx。这类问题看着像灵异事件实际上和 pnpm 最核心的依赖管理机制强相关。这篇教程我会完整帮你拆解Cannot resolve lodash为什么会发生和 npm 的幽灵依赖有什么关系按什么顺序排查最快如何让团队避免再次踩坑。文章会给出具体命令、配置片段和验证方法适合刚接触 pnpm 的开发者也适合正在从 npm 迁移到 pnpm 的团队参考。1. 背景与核心概念1.1 pnpm 是什么和 npm 的核心区别pnpm 是一个 Node.js 包管理器比 npm 和 Yarn 更强调“快”和“省空间”。它的设计核心是所有包统一存储在一个内容寻址的全局 Store 中项目里的node_modules不直接复制完整依赖而是通过硬链接和目录符号链接指向全局 Store每个依赖只允许访问package.json中明确声明的包不允许“越权”访问未声明的包。npm 的传统做法是快速扁平的node_modules结构。安装 A 的时候A 依赖了 Bnpm 会把 B 也平铺到node_modules顶层于是你的项目代码即使没有直接声明 B也能require(B)。这种“没声明也能用”的依赖被称为幽灵依赖Phantom Dependency。pnpm 恰恰是反这种做法的。它会在项目根目录创建一个版本化的.pnpm目录里面按真实的依赖关系放置所有包然后用符号链接暴露给项目。项目代码能访问的仅限于package.json里声明过的依赖。这样虽然增强了规范性和隔离性但如果项目里其实藏着“没被声明、但被代码引用”的包从 npm 切到 pnpm 后就会报Cannot resolve。1.2 lodash 为什么这么常见lodash是 JavaScript 工具函数库几乎每个老项目都会用到。它可能是直接依赖也可能是某个子依赖的依赖。在 npm 扁平目录下即使项目没有直接声明 lodash只要某个子依赖引入了它那么顶层node_modules很可能也会存在 lodash。于是业务代码里可以顺手import _ from lodash并不会报错。但到了 pnpm 环境下业务代码只能解析到package.json里声明的依赖子依赖的 lodash 在符号链接隔离层之外自然就解析不到。这也是新同事拉完项目后启动编译立即出现Cannot resolve lodash的最常见原因。1.3 报错发生的几种典型场景业务代码直接引用了 lodash但package.json没有声明某个中间层/配置工具引用了 lodash但依赖版本范围与 lockfile 不一致lockfile 是从 npm 的package-lock.json迁移过来没有重新生成pnpm-lock.yamlpnpm 版本与项目使用的依赖版本不兼容导致安装阶段部分依赖没有被正确链接某些需要执行构建脚本的原生依赖没有执行approve-builds安装产物不完整间接导致模块无法解析。无论是哪一种排查路径其实是有规律可循的。2. 环境准备与版本说明这篇文章的实操部分会涉及 Node.js、pnpm、npm 等工具。不同团队的版本可能不同所以我先说明一下通用环境要求操作系统Windows / macOS / Linux 均适用Node.js建议使用 20 及以上版本部分较新版本 pnpm 对 Node 版本有最低要求pnpm建议使用 8.x 或 9.x也可以根据项目packageManager字段自动切换包管理器本文以 pnpm 为主npm 仅用于对照说明。如果你的环境还没有安装 pnpm可以参考下面几种常见安装方式。2.1 使用 npm 全局安装 pnpmnpm install -g pnpm安装完成后执行pnpm -v如果控制台提示pnpm : 无法将“pnpm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称说明 pnpm 的安装目录没有添加到系统环境变量 PATH 中。Windows 系统下可以执行npm config get prefix得到全局目录后把它加到系统环境变量的Path中然后重新打开终端。macOS/Linux 下通常会自动配置完成如果不行也可以检查~/.npm-global或~/node_modules/.bin。2.2 使用 Corepack 安装 pnpmNode.js 16.13 原生支持 Corepack可以按项目指定的 pnpm 版本启动corepack enable corepack prepare pnpmlatest --activate然后在项目根目录的package.json中建议增加packageManager字段例如{ packageManager: pnpm9.15.0 }这样团队其他人切换 pnpm 版本时会更方便也能减少因为版本不一致导致的安装差异。2.3 项目基础结构示例后面排查时会频繁提到package.json、pnpm-lock.yaml、node_modules我列一个最小项目结构作为参考my-app/ ├── node_modules/ ├── src/ │ └── utils/ │ └── format.js ├── .npmrc ├── package.json ├── pnpm-lock.yaml └── tsconfig.json其中src/utils/format.js内引用了 lodash// src/utils/format.js import _ from lodash; export function formatNumber(value) { return _.round(value, 2); }这个package.json是一个简化版本待会排查时我们会重点核对 lodash 是否在dependencies或devDependencies中。3. 报错现象与根因分析3.1 先看一下具体报错长什么样开发环境里最常见的报错是这一种来自 Vite 或 Webpack[ERROR] Could not resolve lodash src/utils/format.js:1:9: 1 │ import _ from lodash; ╵ ~~~~~~~~ You can mark the path lodash as external to exclude it from the bundle, which will remove this error.如果是在 Node.js 运行时环境可能是Error: Cannot find module lodash Require stack: - /Users/me/project/src/utils/format.js为什么安装阶段没报错构建阶段才报错因为 pnpm 安装时只负责把依赖放到符号链接区真正解析模块发生在构建器读取源码时。如果构建器或 Node.js 在解析lodash时找不到它就会抛出Cannot resolve。3.2 根因一幽灵依赖这是最常见的原因。项目在 npm 时代没有在package.json中声明 lodash但某个依赖内部使用了 lodashnpm 把 lodash 扁平提升到了顶层node_modules。业务代码“顺手”直接用npm 下完全无感知。切到 pnpm 后符号链接结构不再让业务代码访问未声明依赖于是找不到 lodash。要验证是不是这个原因可以打开项目根目录查看是否存在node_modules/lodashls node_modules/lodash如果 pnpm 安装后根本没有这个目录而package.json里又没有声明 lodash那基本就是幽灵依赖问题。3.3 根因二lockfile 没有重新生成有的项目原本使用 npmnode_modules是按扁平结构生成的。团队切到 pnpm 时如果只是执行了pnpm install并且仓库里已经有package-lock.jsonpnpm 可能会尝试迁移。但迁移过程并不总是完美的尤其是在依赖版本范围、peerDependencies 处理上会有差异。如果pnpm-lock.yaml不是基于当前package.json完整解析的就可能出现某个包没有正确链接的情况。最简单的处理方案是删除旧的 lockfile 和node_modules重新生成。3.4 根因三依赖漏装或构建脚本未执行pnpm 在安装依赖时出于安全考虑默认不会执行依赖包里的preinstall、install、postinstall脚本除非在package.json里配置了pnpm.onlyBuiltDependencies或者在安装时执行pnpm approve-builds。如果 lodash 本身是纯 JavaScript 包不依赖构建脚本问题不大。但 lodash 的某些可变版本或者项目里引用的其他包比如 esbuild、sharp没有构建会间接导致模块结构不完整最终报出无法解析某个子路径。需要注意的是pnpm 在安装结束时会给出提示Ignored build scripts: esbuild, sharp. Run pnpm approve-builds to pick which dependencies should be allowed to run scripts.如果团队直接忽略了这段提示后面构建时就有可能出现解析不到某些包的情况。3.5 根因四Node 版本或 pnpm 版本不匹配pnpm 的新版本对 Node.js 版本有最低要求。比如安装时如果出现ERROR: This version of pnpm requires at least Node.js v22.13 The current version of Node.js is v18.18.0这说明你当前的 Node 版本过低pnpm 的命令执行会异常甚至安装不完整。虽然这个报错和Cannot resolve lodash没有直接关系但版本不匹配导致安装中断同样会造成依赖缺失。所以排查依赖解析问题时不要忽略环境版本检查这是消耗时间最少却常被跳过的步骤。4. 完整排查实战下面我用一个模拟场景带你按顺序排查Cannot resolve lodash问题。假设项目已经在从 npm 切换到 pnpm并且新同事按照 README 的步骤执行了pnpm install。4.1 第一步确认工具版本与安装情况在项目根目录执行node -v pnpm -v如果 pnpm 命令本身报错先解决环境变量或安装问题。参数输出示例v20.11.1 9.15.0如果 pnpm 版本较高而 Node 版本过低建议先升级 Node再继续后面的操作。然后确认 pnpm 是否真的把包安装进来了pnpm list lodash可能的结果└─┬ scope/utils 1.0.0 └── lodash 4.17.21这个结果说明 lodash 确实是某个依赖的子依赖但它不是项目直接依赖。4.2 第二步检查 package.json 是否声明了 lodash打开项目根目录的package.json搜索lodashgrep -n lodash package.json如果没有任何输出说明业务代码使用了 lodash但没有在package.json中声明。这正是幽灵依赖的典型表现。此时需要把 lodash 添加为直接依赖推荐用法pnpm add lodash如果需要类型声明可以一起加pnpm add -D types/lodash添加完成后package.json中会出现{ dependencies: { lodash: ^4.17.21 } }然后再检查pnpm-lock.yaml确认 lodash 已经被提升到项目顶层依赖中。4.3 第三步检查 node_modules 中的符号链接pnpm 使用符号链接把项目可访问依赖暴露到根目录。你可以在项目根目录执行ls -l node_modules/lodash正常情况下输出会指向node_modules/.pnpm/lodash4.17.21/node_modules/lodash类似node_modules/lodash - .pnpm/lodash4.17.21/node_modules/lodash如果这个链接不存在说明 pnpm 认为项目没有直接依赖 lodash所以没有暴露这个链接。这也是为什么业务代码解析不到 lodash 的原因。4.4 第四步清理并重新安装依赖如果确认声明依赖后仍然报错可能是 lockfile 或安装缓存出了问题。最稳妥的复现环境方式# 删除旧依赖目录和 lockfile rm -rf node_modules rm -f pnpm-lock.yaml # 重新安装 pnpm install为了防止误删也可以使用 pnpm 提供的命令pnpm store prune这个命令会清理 Store 中不再被引用的缓存但不会删除项目中的依赖。建议在确定要重新安装时再执行避免拉低团队共享缓存的命中率。重新安装后再运行一次pnpm list lodash如果这次结果里 lodash 的位置变为顶层dependencies: lodash 4.17.21说明项目已经可以正常解析到该模块。4.5 第五步验证构建是否恢复继续执行项目的启动命令例如pnpm run dev或者pnpm run build如果不再出现Cannot resolve lodash说明根因就是依赖未声明或 lockfile 不完整。4.6 第六步处理依赖构建脚本授权问题如果项目里包含原生依赖比如 esbuild、sharp、better-sqlite3在 pnpm 下安装时可能会看到类似提示Ignored build scripts: esbuild, sharp. Run pnpm approve-builds to pick which dependencies should be allowed to run scripts.这时按提示执行pnpm approve-builds然后根据交互界面选择允许执行的依赖。如果希望在配置中固化授权列表可以在package.json中增加{ pnpm: { onlyBuiltDependencies: [esbuild, sharp] } }再执行pnpm install这样可以确保团队环境一致不用每个成员都手动approve-builds。5. 常见问题与排查思路我把 pnpm 使用过程中常见的报错和解决思路整理成了一个表格方便快速定位。问题现象常见原因解决思路Cannot resolve lodash项目未显式声明 lodash存在幽灵依赖在package.json中添加 lodash 依赖然后pnpm installCannot find module lodashlockfile 与 package.json 不一致删除node_modules和pnpm-lock.yaml重新安装pnpm : 无法将“pnpm”项识别为 cmdlet...pnpm 全局安装目录未加入 PATH配置环境变量或在已识别 pnpm 的终端中执行命令this version of pnpm requires at least Node.js v22.13Node.js 版本过低升级 Node.js 到 pnpm 要求的最低版本Ignored build scriptspnpm 默认不执行依赖的构建脚本使用pnpm approve-builds或配置pnpm.onlyBuiltDependenciespnpm install速度很慢网络问题或镜像源未配置配置.npmrc中的 registry 镜像地址使用 npm 生成的项目在 pnpm 下构建失败npm 的扁平目录结构掩盖了依赖关系检查所有源码 import 是否都有显式依赖声明如果你遇到类似报错可以按下面顺序排查先看package.json中是否声明了报错模块再看node_modules中是否存在对应符号链接接着检查 lockfile 是否是最新生成的然后确认 Node.js 版本满足 pnpm 要求最后确认需要构建脚本的依赖是否被 pnpm 阻止执行。大多数Cannot resolve类问题前两步就能定位。6. 最佳实践与工程建议6.1 显式声明所有依赖消灭幽灵依赖团队从 npm 迁移到 pnpm 时最值得投入的一件事就是清理幽灵依赖。推荐在项目里引入 ESLint 插件eslint-plugin-import开启import/no-extraneous-dependencies规则禁止源码引用未声明依赖。例如{ rules: { import/no-extraneous-dependencies: [error, { devDependencies: [**/*.test.js, **/*.spec.js] }] } }这能强制开发者把依赖写到package.json中从源头避免Cannot resolve问题。6.2 使用 packageManager 固定 pnpm 版本团队协作中不建议每个成员都手动全局安装最新版 pnpm。推荐在package.json中声明packageManager{ packageManager: pnpm9.15.0 }同时结合 Corepack可以确保团队成员使用同一版本。即使有人没有全局安装 pnpm在项目目录下执行corepack prepare也能自动拉取对应版本。6.3 提交 pnpm-lock.yaml并统一安装命令pnpm 的 lockfile 是保证依赖可复现的核心。建议pnpm-lock.yaml必须提交到 Git 仓库不要每次遇到问题就直接删除 lockfile如果确实需要重新生成确保是在代码分支上基于正确的package.json执行。日常安装依赖时优先使用pnpm install而不是pnpm add各种包这样锁文件更新会更可控。6.4 配置 .npmrc 镜像源与 store 路径国内团队经常会遇到 pnpm 安装超时的问题。可以在项目根目录创建.npmrc文件registryhttps://registry.npmmirror.com store-dir.pnpm-store其中registry指定 npm 镜像源store-dir可以把 pnpm 的全局 Store 收敛到项目目录内方便清理和管理。如果公司有私有镜像源优先使用私有源。6.5 在 CI 环境中同样使用 pnpm为了避免本地和 CI 行为不一致建议 CI 脚本也使用 pnpm。例如 GitHub Actions 中可以使用- uses: pnpm/action-setupv4 with: version: 9.15.0 - uses: actions/setup-nodev4 with: node-version: 20 cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm run build--frozen-lockfile是 CI 中很重要的参数它要求 lockfile 与package.json完全一致避免 CI 环境自动改动锁文件。6.6 涉及安全与生产环境变更时保持谨慎在排查依赖问题时会涉及删除node_modules、清理 pnpm Store、修改 lockfile 等高影响操作。请注意优先在独立分支或本地验证不要在正在运行的生产环境执行清理缓存前先确认 Store 中不存在其他项目共享引用如果涉及生产构建建议先备份 lockfile 和package.json权限管理遵循最小权限原则不要随意以管理员权限执行包管理命令。7. 总结与学习路线回到最初的问题新同事用 pnpm 拉项目报错Cannot resolve lodash。这个问题的本质是 pnpm 严格依赖隔离后项目里原本未声明的幽灵依赖暴露了出来。解决办法也很直接——在package.json中显式声明 lodash然后重新pnpm install。这个过程看起来简单但背后涉及 pnpm 的符号链接结构、lockfile 机制、构建脚本授权、环境版本匹配等多层知识。如果只是搜到一个“执行 pnpm add lodash”的答案下一次遇到Cannot resolve xxx可能还是不会排查。建议下一步按这个顺序深入学习阅读 pnpm 官方文档中关于 node_modules 结构的说明了解 npm 扁平化目录与 pnpm 符号链接目录的区别熟悉pnpm-lock.yaml的 import 与解析方式在 monorepo 项目中使用 pnpm workspace了解 pnpm 的 store、hard link 和内容寻址存储原理。最后分享一个团队里的实用技巧遇到 pnpm 下的模块解析报错先不要急着删node_modules打开package.json检查依赖是不是漏写了。80% 的Cannot resolve都能在这一步找到答案。希望这篇教程能帮你少走弯路。
