同级依赖

同级依赖是 npm 的一项功能。包会在其 package.json 中声明它们，表示它期望安装它的项目提供另一个包的兼容副本，而不是把自己的副本打包进去：

{
  "name": "some-react-plugin",
  "peerDependencies": {
    "react": "^19"
  }
}

插件和扩展使用同级依赖，这样插件和宿主就能共享同一个包副本。例如，React 组件库会将 react 声明为同级依赖，这样它就能使用你的应用已经在用的那个完全一致的 React，而不是引入第二个、可能不匹配的副本。

peerDependencies 位于 package.json 中，而不是 deno.json Jump to heading#

peerDependencies 是 package.json 的一个字段，也是 Deno 读取同级依赖的唯一来源。deno.json 没有 peerDependencies 字段，也没有等效项。 其中的 imports 映射将模块说明符解析到具体位置；它是一个导入映射，而不是像 npm 那样区分普通依赖、开发依赖和同级依赖的清单文件。

在实践中，这意味着：

• 编写包。 如果你发布的包需要宿主项目提供某个依赖，你应在 package.json 中使用 peerDependencies 声明它。无法在 deno.json 中表达这一点。
• 使用包。 当你安装一个 npm 包时，Deno 会读取它的 peerDependencies 并从你项目的依赖图中解析它们，方式与 npm 相同。只要让该包在你的项目中可解析，你就满足了一个同级依赖，无论你的项目使用的是 deno.json 还是 package.json。

提供同级依赖 Jump to heading#

将同级依赖与需要它的包一起添加。在 deno.json 项目中，把两者都列在 imports 中：

{
  "imports": {
    "react": "npm:react@^19",
    "some-react-plugin": "npm:some-react-plugin@^1"
  }
}

这样 some-react-plugin 就会将其 react 同级依赖解析为你的应用导入的同一个 npm:react@^19。这里你并没有声明一个同级依赖；你只是让 react 在图中可用，以便插件声明的同级依赖能够解析到它。在 package.json 项目中，你将 react 列在 dependencies 中，和在 Node 中的做法完全一样。

node_modules 布局与同级依赖 Jump to heading#

同级依赖如何解析取决于 Deno 使用的 node_modules 布局。

在默认的 isolated 布局中，每个包只能看到它声明的依赖，因此同级依赖必须由你的项目提供（如上所示），包才能找到它。这样可以尽早捕获缺失的同级依赖，而不是让包意外解析到一个它从未声明过的兄弟依赖。

某些 npm 工具假定使用 npm 和 Yarn classic 所用的 hoisted 布局，其中依赖会被扁平化到 node_modules 顶层。如果某个包在 node_modules 中查找同级依赖，按扁平解析的兄弟包方式查找却找不到，请切换到 hoisted 链接器（这需要一个手动管理的 node_modules 目录）：

{
  "nodeModulesDir": "manual",
  "nodeModulesLinker": "hoisted"
}

可选同级依赖 Jump to heading#

包可以通过其 package.json 中的 peerDependenciesMeta 将某个同级依赖标记为可选：

{
  "peerDependencies": {
    "react": "^19"
  },
  "peerDependenciesMeta": {
    "react": { "optional": true }
  }
}

只有当你使用依赖它的功能时，才需要提供可选同级依赖。例如，一个支持多个框架的包可能会把每个框架都列为可选同级依赖，并使用你已经安装的那个。

修复未满足的同级依赖 Jump to heading#

如果某个包的同级依赖不存在，导入它会因缺少的包而失败，并报出 module-not-found 错误。要修复它，请将该同级依赖添加到项目的依赖中，然后运行 deno install，这样该版本就会成为你依赖图的一部分：

deno install

如果该包预期是在 node_modules 中作为 hoisted 兄弟包找到同级依赖，请参见 node_modules 布局，并按上面所示切换到 hoisted 链接器。有关 Deno 如何与 npm 包和 node_modules 协同工作的更多信息，请参见 Node 兼容性。