deck.gl 项目中使用 pnpm 安装依赖的注意事项

背景介绍

deck.gl 是一个由 Uber 开发的开源 WebGL 数据可视化框架，它提供了丰富的地理空间数据可视化能力。随着 TypeScript 在前端生态中的普及，越来越多的开发者选择使用 TypeScript 来开发基于 deck.gl 的应用。

问题现象

当开发者使用 pnpm 作为包管理器安装 deck.gl 时，可能会遇到一个特殊问题：即使已经执行了 pnpm install deck.gl 命令，在代码中导入 @deck.gl/react/typed 或 @deck.gl/layers/typed 时，TypeScript 仍然会报错提示找不到模块。

问题原因

这个问题源于 pnpm 的设计哲学。与 npm 和 yarn 不同，pnpm 采用了一种更严格的依赖管理策略：

1. pnpm 要求所有直接使用的包都必须显式声明为依赖
2. 即使某个包是另一个包的依赖项，如果代码中直接引用了它，也需要显式安装
3. deck.gl 虽然在其 package.json 中包含了所有子模块作为依赖，但 pnpm 不会自动将这些子模块提升到项目根目录的 node_modules 中

解决方案

要解决这个问题，开发者需要显式安装直接引用的 deck.gl 子模块：

pnpm install @deck.gl/layers
pnpm install @deck.gl/react

或者直接在项目的 package.json 中声明这些依赖：

{
  "dependencies": {
    "@deck.gl/layers": "^8.9.34",
    "@deck.gl/react": "^8.9.34"
  }
}

技术细节

1. pnpm 的严格模式：pnpm 通过符号链接和硬链接来管理依赖，确保每个包只安装一次，这提高了安装效率和磁盘空间利用率，但也带来了更严格的依赖要求。

2. deck.gl 的模块结构：deck.gl 采用模块化设计，核心功能被拆分到不同的子模块中，主包 deck.gl 主要作为这些子模块的集合。

3. TypeScript 类型解析：当使用 /typed 路径导入时，TypeScript 需要能够解析对应的类型声明文件，这要求相关的包必须被正确安装。

最佳实践

1. 在使用 pnpm 时，建议显式声明所有直接引用的 deck.gl 子模块
2. 对于新项目，可以在初始化时就安装所有需要的子模块
3. 在团队协作项目中，确保 package.json 中包含了所有必要的 deck.gl 子模块依赖

总结

虽然 pnpm 的严格依赖管理策略在初期可能会带来一些适应成本，但它能够帮助开发者更清晰地管理项目依赖，避免潜在的依赖冲突问题。对于 deck.gl 用户来说，理解并遵循 pnpm 的这些规则，可以确保项目能够顺利构建和运行。