企业官网建设流程全解析

• 包管理器
• 开发工具
• CLI

导读

@pnpm/modules-mounter.daemon是 pnpm 11 实验链路中的关键组件：它不再把 store 里的包文件复制或硬链接到node_modules，而是通过 FUSE 把一个虚拟的 node_modules 目录挂载到工作区，所有文件读取请求在运行时由 FUSE 回调转译为对内容寻址存储（CAFS）的访问。读完本文，你将掌握mount-modules/unmount两个命令的完整使用流程、FUSE 挂载的适用前提，以及从 lockfile 到虚拟目录、再到 FUSE 回调的完整实现原理，并能在源码与测试用例中验证每一步行为。

一、背景：为什么要用 FUSE 挂载 node_modules

传统 pnpm 安装会在磁盘上真实创建node_modules目录树：store 中的包通过硬链接/软链接被"物化"到项目目录。这种方式虽然磁盘占用小，但仍需要在文件系统上写入大量目录项与链接。

modules-mounter的思路是从 lockfile 出发，在内存中构建一棵虚拟目录树，再用 FUSE 把它映射为一个可被 Node.js 正常访问的挂载点。包的真实文件仍然只存在于 store（CAFS）中，按内容摘要（digest）寻址，只有被打开/读取时才会真正触及磁盘。从 README.md 的定位 "Mounts a node_modules directory with FUSE" 以及 package.json 的描述可以确认，这正是该模块的核心目标。

需要特别说明的是，这是一个实验性能力：它依赖原生模块fuse-native（在 package.json 中被声明为optionalDependencies），要求操作系统提供 FUSE 内核支持（Linux 或 macOS 的 macFUSE 等），并非所有平台默认可用。Node.js 版本要求为>=22.13。

二、安装

与 pnpm 的大部分功能包一样，该守护进程以全局包形式安装，二进制入口为mount-modules：

pnpm add @pnpm/modules-mounter.daemon --global

从 package.json 可以看到：

• bin字段指向bin/mount-modules.js，即安装后全局命令mount-modules的入口；
• 依赖@pnpm/config.reader、@pnpm/store.path、@pnpm/store.cafs、@pnpm/store.index、@pnpm/lockfile.fs、@pnpm/lockfile.utils等工作区包，分别负责配置读取、store 路径解析、CAFS 文件索引与 lockfile 解析；
• 运行环境要求 Node.js>=22.13（源码使用 ESM，"type": "module"）。

三、使用步骤

3.1 第一步：把包全部取到 store

挂载前，所有包必须已经下载到 store 中。README 给出的做法是不安装、只生成并解析 lockfile：

pnpm install --lockfile-only

这一步确保 pnpm-lock.yaml 存在且其中packages/snapshots段记录的所有包都已存在于 store。原因在源码中非常清晰：createFuseHandlers.ts 的createFuseHandlers会先调用readWantedLockfile读取 lockfile，若不存在则直接抛错：

const lockfile = await readWantedLockfile(lockfileDir, { ignoreIncompatible: true }) if (lockfile == null) throw new Error('Cannot generate a .pnp.cjs without a lockfile')

而包内容的解析则完全依赖 CAFS 索引（见下文源码剖析），store 里没有对应内容时挂载后的文件将无法读取。

3.2 第二步：挂载虚拟 node_modules

在项目根目录（包含 lockfile 的目录）执行：

mount-modules

CLI 逻辑位于 cli.ts，其行为是：

1. 以当前工作目录为基准，把挂载点固定为path.join(process.cwd(), 'node_modules')，并递归创建该目录；
2. 通过getConfig读取 pnpm 配置，再用getStorePath解析出真实 store 路径（默认来自配置storeDir）；
3. 基于createFuseHandlers(process.cwd(), storeDir)构建 FUSE 回调，创建new Fuse(mnt, handlers, { debug: true })并调用fuse.mount()；
4. 注册SIGINT信号处理：收到 Ctrl+C 时调用fuse.unmount()优雅卸载，并输出对应日志。

也就是说，mount-modules总是在当前目录下挂载node_modules，因此必须在目标项目根目录中运行。

3.3 第三步：卸载

如果出现异常导致挂载的目录无法访问，使用 README 提供的卸载命令：

unmount <path to node_modules>

卸载后，挂载点恢复为普通目录，可以重新执行mount-modules再次挂载。

四、底层实现剖析：从 lockfile 到虚拟文件系统

4.1 内存虚拟目录树：makeVirtualNodeModules

挂载的"目录结构"并不存在于磁盘，而是由 makeVirtualNodeModules.ts 在内存中构建的一棵DirEntry树。节点分为三类：

• directory：普通目录，含entries子节点表；
• symlink：符号链接，含target字符串（与真实 pnpm 布局一致，仍采用符号链接表达依赖关系）；
• index：指向某个包的内容索引，记录其depPath，真正的文件列表在运行时按需从 store 索引中解析。

树的构建规则与 pnpm 标准布局一一对应：

• 根目录下自动创建.pnpm虚拟 store 目录（对应createVirtualStoreDir），以及来自lockfile.importers['.']各依赖字段（DEPENDENCIES_FIELDS）的顶层符号链接，如is-positive -> ./.pnpm/is-positive@1.0.0/node_modules/is-positive；
• .pnpm内按depPath转文件名（depPathToFilename，路径长度上限 120）建立包目录，每个包目录下有node_modules/<pkgName>指向该包的index节点；
• 包内部依赖同样以相对符号链接表达，例如快照测试中ini被表达为../../ini@1.3.4/node_modules/ini（见 makeVirtualNodeModules.test.ts.snap）。

4.2 FUSE 回调：createFuseHandlers

createFuseHandlers.ts 实现了挂载点对内核/用户态文件系统请求的全部响应逻辑，FuseHandlers接口包含六个操作：

关键设计在getDirEnt与getPkgInfo两个内部函数：

• getDirEnt沿着虚拟目录树逐级查找路径，若命中index节点，则通过getPkgInfo从StoreIndex取回该包完整的PackageFilesIndex（文件路径 → digest/mode/size 映射），并把路径剩余部分作为subPath传入；
• getPkgInfo先查pkgSnapshotCache（以depPath为 key 的内存缓存），未命中时从 lockfile 的packages段取PackageSnapshot，用pickStoreIndexKey计算 store 索引键并读取PackageFilesIndex。这解释了为何必须先把包取到 store：挂载时的文件元数据完全来自 CAFS 索引。

getattr对index节点进一步调用cafsExplorer.dirEntityType判断路径是文件还是目录，再决定返回文件 stat 或目录 stat；readdir则用cafsExplorer.readdir按路径前缀聚合目录项。

4.3 目录枚举的纯内存实现：cafsExplorer

cafsExplorer.ts 只有两个函数，是"零磁盘扫描"的关键：

• readdir(index, dir)：遍历该包files的全部键（形如lib/index.js），把以dir/为前缀的路径按第一段聚合成目录项集合；
• dirEntityType(index, p)：若p本身是文件键则为file，否则若存在以p/为前缀的键则为directory，否则返回undefined（映射为ENOENT）。

也就是说，目录枚举不产生任何 stat 系统调用，只做字符串前缀匹配，这也是虚拟挂载方案相比真实目录树的核心优势。

4.4 模块公开 API

src/index.ts 只导出三个符号：createFuseHandlers、createFuseHandlersFromLockfile与类型FuseHandlers。前者面向"给定 lockfile 目录 + store 目录"的使用场景；后者直接接受已解析的LockfileObject，便于测试与复用。

五、测试验证：行为即规范

模块自带两个 Jest 测试，直接对 FUSE 回调做断言（测试中通过jest.unstable_mockModule把fuse-native替换为仅含ENOENT的 mock，无需真实 FUSE 环境即可单测）：

• createFuseHandlers.test.ts 使用__fixtures__/simple夹具，验证了：
  • readdir('/')返回.pnpm、@zkochan、is-positive；readdir('/.pnpm')返回@zkochan+git-config@0.1.0、ini@1.3.4、is-positive@1.0.0，与内存虚拟树一致；
  • getattr对index.js返回文件 mode（33206，即普通文件 100644）、对test/fixtures返回目录 mode（16877），对不存在的index.jsx返回ENOENT；
  • open+read+release全链路：打开 store 中真实文件后，read10 字节得到'var ini = '——证明读取最终落到 store 中的真实文件内容；
• makeVirtualNodeModules.test.ts 对虚拟目录树做快照断言，其快照 makeVirtualNodeModules.test.ts.snap 展示了顶层符号链接is-positive -> ./.pnpm/is-positive@1.0.0/node_modules/is-positive与包内相对链接ini -> ../../ini@1.3.4/node_modules/ini的完整形态。

另外 package.json 的pretest脚本会在测试前用pnpm install --dir=test/__fixtures__/simple真实安装夹具项目，保证测试用 store 是真实可读的——这从侧面印证了"挂载前必须先 install 到 store"的前置流程。

六、适用前提与限制（基于当前仓库事实）

• 系统层面：需要 FUSE 内核能力与fuse-native原生模块可用，否则挂载会失败；fuse-native在 package.json 中是optionalDependencies，安装时可被跳过；
• Node 版本：要求>=22.13，且包为 ESM；
• 工作目录：mount-modules固定挂载process.cwd()/node_modules，请在项目根目录执行；
• store 前置：必须先用pnpm install --lockfile-only把包取到 store，否则 FUSE 回调在getPkgInfo阶段拿不到PackageFilesIndex，文件访问将失败；
• 实验属性：该模块处于 pnpm 11 的 modules-mounter 实验链路中（仓库路径 pnpm11/modules-mounter/daemon），本文结论均以当前仓库源码与测试为准，具体可用性请以你所用版本的发布说明为准。

七、总结

@pnpm/modules-mounter.daemon完整回答了"能否不落盘 node_modules 就使用依赖"这一命题：lockfile 提供依赖图，StoreIndex 提供文件索引，FUSE 提供系统调用到内存树的桥接。其使用流程极简——pnpm install --lockfile-only取包、mount-modules挂载、unmount卸载；其实现则是一棵由makeVirtualNodeModules构建、由createFuseHandlers按需访问 CAFS 的纯内存虚拟文件树。对于希望在 CI、缓存受限或对磁盘写入敏感的场景中探索免安装依赖的实验性方案，这个模块是一个值得研究的技术范本。

• 包管理器
• 开发工具
• CLI