当前位置：首页 > news >正文

npm幻影依赖问题

news 来源：原创 2025/5/26 5:24:03

你可以看到，很多前端工程已经不再使用 npm 来管理包，而是转向了 pnpm，其背后有很多原因，其中一个重要的就是它能彻底解决“幻影依赖”的问题。下面我们先来聊聊什么是幻影依赖，是什么造成的，又该如何解决。

首先，看一个简单的例子：我们的工程里只在 package.json 中声明了两个生产依赖和两个开发依赖，按理说 node_modules 目录下也就只有这四个包。但安装后你会发现目录里多了一堆额外的包，比如一个叫 loadash的模块——我们并没有在声明里依赖它，却能在代码中这样写：

// 在 media.js 中
import loadash from 'loadash';
console.log(loadash());

运行 npm run dev，能够正常打印出结果，看似没问题。但实际上，这就是典型的幻影依赖：你在代码里使用了一个并未在 <u>dependencies</u> 或 <u>devDependencies</u> 中显式声明的包，依赖树里之所以能找到它，是因为它被你的其他依赖间接带入了。

版本问题（A 依赖 B，项目直接使用 B。之后更新 A 版本，也会更新 B 版本，导致项目其他地方使用 B 不兼容）
设想包 A（版本 v1）间接依赖了包 B（版本 v1），而你的代码又直接使用了 B。在最初一切正常，但当你把 A 升级到 v2 时，如果它更新了对 B 的依赖，把 B 一并升级到了 v2，就可能引入不兼容的改动。此时，你会发现 B 出了问题，却完全不知道原因，因为你并没有在自己的 package.json 中声明 B。

依赖丢失问题（开发环境依赖 A（间接依赖 B），当生产环境 AB 都不能使用）
在生产环境里通常只安装 dependencies，跳过 devDependencies。如果某个开发依赖 A 间接带入了 B，而代码错误地通过幻影依赖使用了 B，那么在生产环境安装时就不会安装 A（也就没有 B），导致运行时报错。你本地一切正常，一上传部署就报错，又要大费周章地排查。

依赖关系本质上是一个有向图，包 A 依赖 B，B 又可能依赖 C……而文件系统只能表现为树结构。早期的 npm 做法是把这张依赖图“展开”成一棵树——每个包都拷贝一份到它父包的 node_modules 目录下，这样既能表达依赖图，又不会出现幻影依赖。只是带来了两个新问题：

Yarn 首先引入了“扁平化”管理——把所有依赖都统一放到项目根目录下的单一 node_modules，用扁平结构解决了深嵌套和重复问题。但扁平化的同时，就引入了幻影依赖：所有间接依赖也被提到根目录，你可以直接 import 它们，却并未声明。

pnpm 保留了扁平化的优势，又杜绝了幻影依赖。它的核心做法是：

集中存储
所有包文件都存放到一个全局内容寻址的仓库（store）中，且只保留一份。
硬链接/软链接
在项目的 node_modules 下创建指向仓库中真实文件的“快捷方式”（硬链接或软链接），几乎不占磁盘空间，且层级扁平。
模块隔离
你在项目里能 import 的，只有 node_modules 目录下实际存在的链接。仓库里的存储区你无法直接 import，从而保证你只能使用在 package.json 明确声明的依赖。

举个简单的实验：

删除项目的 node_modules，改用 pnpm install 重装。
此时 node_modules 里干干净净，只剩下四个我们声明的包，直接或间接依赖都不会被“提平”到根目录。
再在 media.js 中尝试 import loadAssy from 'loadAssy'，立刻就会报错：找不到模块。幻影依赖无处可藏，早早在编译时就能暴露错误，让我们无法再误用未声明的包。