pnpm 10.0.0-rc.0 版本中关于依赖安装的重要变更解析

在 pnpm 10.0.0-rc.0 版本中，开发者们发现了一个与依赖安装行为相关的重要变更。这个变更影响了项目中如何访问和使用传递性依赖（transitive dependencies），特别是当这些依赖被直接引用但未被显式声明为项目依赖时的情况。

问题现象

在 pnpm 9.15.1 版本中，当安装 eslint 作为开发依赖时，其传递性依赖（如 @eslint/js）会被自动提升（hoist）到项目的 node_modules 根目录下。这使得开发者可以直接在代码中引用这些传递性依赖，即使它们没有被显式声明为项目依赖。

然而，在 pnpm 10.0.0-rc.0 版本中，这种行为发生了变化。传递性依赖不再被自动提升到 node_modules 根目录，而是保留在 .pnpm 目录中。这导致当代码尝试直接引用这些传递性依赖时，会出现模块找不到的错误。

技术背景

pnpm 使用一种独特的依赖管理策略，通过符号链接和硬链接来优化存储空间和安装速度。在 pnpm 9 及更早版本中，某些情况下会自动将传递性依赖提升到 node_modules 根目录，以兼容一些工具和框架的预期行为。

从 pnpm 10 开始，团队决定改变这一行为，使依赖管理更加严格和明确。这一变更与 Node.js 生态系统中提倡的显式依赖声明原则一致，有助于减少隐式依赖带来的潜在问题。

解决方案

对于遇到此问题的开发者，正确的解决方法是：

1. 显式声明所有直接引用的依赖：如果代码中直接引用了某个包（如 @eslint/js），应该将其明确添加到项目的 package.json 文件中作为依赖项。

2. 理解依赖管理的正确实践：传递性依赖应该被视为实现细节，不应该在代码中直接引用。这种实践有助于提高项目的可维护性和稳定性。

3. 评估升级影响：在升级到 pnpm 10 之前，检查项目中是否存在对传递性依赖的直接引用，并做好相应的调整。

最佳实践

为了避免类似问题，建议开发者遵循以下最佳实践：

• 始终显式声明项目直接使用的所有依赖
• 避免在代码中直接引用传递性依赖
• 在升级包管理器大版本时，仔细阅读变更日志和迁移指南
• 使用 pnpm ls 命令检查项目的依赖树结构

这一变更虽然可能导致一些现有项目需要调整，但从长远来看，它有助于建立更加健壮和可维护的依赖管理实践。开发者应该将此视为改进项目结构的机会，而不是简单地寻找变通方案。