> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/contributor-zh/gong-xian-zhe-zhi-nan/dependency-management.md).

# 依赖管理

本文档定义了在 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 节](#4-examples) 了解常见包及其推荐放置位置。

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

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

* React、Redux、wagmi、ethers、viem
* @dcl/schemas 及类似的跨生态库
* decentraland/connect
* 在共享连接池时使用数据库驱动
* 任何依赖单例或上下文的库

✅ 正确（库）：

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

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

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

### 使用 dependencies 用于：

* 可安全重复的工具（lodash-es、date-fns）
* **在应用中**：运行时包，如 React、ethers（当应用是最终消费者时）

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

✅ 正确（库）：

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

✅ 正确（应用）：

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

### 可选 peerDependencies（peerDependenciesMeta）

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

✅ 正确：

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

**这意味着：**

* `react` 为 **必需**：消费者必须安装它，否则包管理器会警告
* `ethers` 为 **可选**：消费者无需安装它；你的包应在使用前检查其是否存在

**用例：**

* 可在 React 和非 React 环境中运行的包
* 支持多个 Web3 提供者（ethers、viem 等）的库
* 增强其他库但并非必需的工具

### 使用 devDependencies 用于：

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

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

✅ 正确：

```json
{
  "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. 相关标准

* [测试标准](/contributor/contributor-zh/gong-xian-zhe-zhi-nan/testing-standards.md)
* [UI 标准](https://github.com/decentraland/docs/blob/main/contributor/contributor-guides/ui-standards/README.md)
* [Web UI 标准](https://github.com/decentraland/docs/blob/main/contributor/contributor-guides/web-ui-standards/README.md)
* [WKC 架构](https://github.com/decentraland/docs/blob/main/contributor/contributor-guides/well-known-components/README.md)
* [API 文档指南](/contributor/contributor-zh/gong-xian-zhe-zhi-nan/api-documentation.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/contributor/contributor-zh/gong-xian-zhe-zhi-nan/dependency-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.