依赖管理

本文档定义了在 Decentraland 生态系统中管理 JavaScript/TypeScript 项目依赖项的推荐实践。它适用于前端、后端、SDK、共享库，以及任何基于 npm/yarn/pnpm 的包。

简而言之:

• 版本策略 → 使用 精确/固定版本 用于 依赖 （安全性）以及 devDependencies （一致的开发环境）。使用 版本范围 仅用于 peerDependencies （灵活性）。

• 例外 → Decentraland 包（@dcl/*, decentraland-*）可使用版本范围（^），因为它们是受信任的内部包。

• 库/共享包 → 使用 peerDependencies 对共享库使用版本范围（^）（React、@dcl/schemas 等）。使用 依赖 仅对可安全重复的工具使用精确版本。

• 应用/最终服务 → 使用 依赖 对运行时包使用精确版本（React、ethers 等）。

1. 理由

许多库依赖全局单例、React Context、类标识、共享缓存、schema 枚举或共享数据库连接池。安装同一库的多个版本可能导致：

• 不同副本之间不共享上下文

• 重复的缓存或连接池

• instanceof 检查失败

• 枚举/符号不匹配

• 增加打包体积

• 难以诊断的运行时 bug

正确的依赖管理可避免这些问题。

非目标

本标准不 不是 试图：

• 强制使用单一包管理器（npm、yarn、pnpm 均受支持）

• 保证在 node_modules 中只有一个物理副本（重点是运行时/打包体去重）

2. 定义

字段	目的	消费者责任	适用于
依赖	模块内部使用的包	无——不期望由消费者提供它们	应用和库
peerDependencies	运行时必须解析为单一有效版本的包	必须安装它们（或使用 peerDependenciesMeta 表示可选）	仅限库
peerDependenciesMeta	用于 peerDependencies 的元数据，用来将对等项标记为可选	无——仅影响包管理器行为	仅限库
devDependencies	仅在开发期间使用的工具	无	应用和库

关于 peerDependenciesMeta

peerDependenciesMeta 是一个提供有关你的 peerDependencies的元数据字段。最常见的用例是将对等项标记为 可选:

• 必需的对等项 （默认）：如果未安装，包管理器会警告

• 可选的对等项：如果缺失，包管理器不会警告；你的包应优雅地处理它们的缺失

这对那些可以在有无某些依赖的情况下工作的包很有用（例如，一个既可在 React 环境也可在非 React 环境下工作的工具，或一个支持多个 Web3 提供者的库）。

应用 vs 库

库 / 共享包：

• 使用 peerDependencies 用于运行时必须解析为单一有效版本的包（React、ethers、@dcl/schemas）

• 消费者（应用）提供这些依赖

• 防止重复安装和单例冲突

应用 / 最终服务：

• 通常使用 依赖 用于运行时包（React、ethers 等）

• 它们是最终消费者，因此无需担心重复

• peerDependencies 如果该应用未来可能作为依赖被使用，这仍然有效

3. 何时使用各字段

快速参考：参见 第 4 节 了解常见包及其推荐放置位置。

在以下情况下使用 peerDependencies（仅限库）：

在共享库/包中，使用 peerDependencies 用于必须在运行时解析为单一有效版本的包：

• React、Redux、wagmi、ethers、viem

• @dcl/schemas 及类似的跨生态库

• decentraland/connect

• 在共享连接池时使用数据库驱动

• 任何依赖单例或上下文的库

✅ 正确（库）：

{
  "peerDependencies": {
    "react": "^18.0.0",
    "@dcl/schemas": "^20.0.0"
  }
}

❌ 错误（库将共享库放入 dependencies）：

{
  "dependencies": {
    "react": "^18.0.0"
  }
}

使用 dependencies 用于：

• 可安全重复的工具（lodash-es、date-fns）

• 在应用中：运行时包，如 React、ethers（当应用是最终消费者时）

重要：始终在 精确/固定版本 中 依赖 出于安全考虑。

✅ 正确（库）：

{
  "dependencies": {
    "lodash-es": "4.17.21",
    "date-fns": "3.6.0"
  }
}

✅ 正确（应用）：

{
  "dependencies": {
    "react": "18.3.1",
    "ethers": "6.13.0",
    "lodash-es": "4.17.21"
  }
}

可选 peerDependencies（peerDependenciesMeta）

对于可复用且可在有无某些依赖下工作的包，使用 peerDependenciesMeta 来将对等项标记为可选：

✅ 正确：

{
  "peerDependencies": {
    "react": "^18.0.0",
    "ethers": "^6.0.0"
  },
  "peerDependenciesMeta": {
    "ethers": {
      "optional": true
    }
  }
}

这意味着：

• react 为 必需：消费者必须安装它，否则包管理器会警告

• ethers 为 可选：消费者无需安装它；你的包应在使用前检查其是否存在

用例：

• 可在 React 和非 React 环境中运行的包

• 支持多个 Web3 提供者（ethers、viem 等）的库

• 增强其他库但并非必需的工具

使用 devDependencies 用于：

• 工具链（TypeScript、ESLint、测试器、打包器）

重要：始终在 精确/固定版本 中 devDependencies 以确保整个团队拥有一致的开发环境。

✅ 正确：

{
  "devDependencies": {
    "typescript": "5.4.5",
    "eslint": "8.57.0",
    "vitest": "1.6.0"
  }
}

4. 示例

必须使用 peerDependencies 的包（共享上下文 / 单例）

• react, react-dom, react-redux, react-router-dom

• redux, @reduxjs/toolkit

• ethers, viem, wagmi

• @dcl/schemas, @dcl/ui-env, @dcl/crypto

• decentraland-dapps, decentraland-ui, decentraland-ui2, decentraland-connect

• pg, pg-pool

应该使用 dependencies 的包（可安全重复）

• lodash-es, date-fns

• uuid, nanoid

• zod, ajv

• ms, mitt, fp-future

5. 相关标准

• 测试标准

• UI 标准

• Web UI 标准

• WKC 架构

• API 文档指南