pnpm 的 node_modules 采用非扁平化布局:根目录下仅通过符号链接暴露项目在 package.json 中显式声明的直接依赖,所有间接依赖(传递依赖)都被封装在 .pnpm 虚拟存储目录内。这种结构确保项目代码只能 require 或 import 已在 package.json 中登记的包,无法访问未经声明的传递依赖。
默认情况下,pnpm 采用半严格模式(semistrict):node_modules 内部的包可以访问通过提升规则允许的未声明依赖,但 node_modules 外部的代码无法访问其中的内容。若需要更严格的隔离,可在 .npmrc 中设置 hoist=false,完全禁止依赖提升,此时只有显式声明的依赖才可访问。对于绝大多数现代项目,半严格模式已在保证兼容性的同时提供了足够的隔离性。
严格隔离机制会迫使开发者将实际使用的依赖显式写入 package.json。当代码中尝试引用未声明的包时,运行时会立即抛出 Cannot find module 错误,而非像传统方案那样因提升机制而"恰好可用"。这种即时反馈帮助团队在开发阶段就发现依赖声明遗漏,避免生产环境中因传递依赖升级或移除而导致的隐蔽故障。