如何强制用户安装与依赖B使用版本一致的依赖A？

实际案例背景 #

@yamato-daiwa/es-extensions-localization-japanese@1.5.0-alpha.0 版本依赖 @yamato-daiwa/es-extensions@1.5.1，原包package.json配置如下：

{
  "name": "@yamato-daiwa/es-extensions-localization-japanese",
  "version": "1.5.0-alpha.0",
  "dependencies": {
    "@yamato-daiwa/es-extensions": "1.5.1"
  },
  "peerDependencies": {
    "@yamato-daiwa/es-extensions": ">=1.5.0 <1.6.0"
  }
  // ...其余配置省略
}

正常安装状态 #

当用户项目中安装版本匹配的两个依赖时，两个包都会被提升到node_modules/@yamato-daiwa目录下，不会出现重复实例，对应目录结构：

用户项目侧package.json参考配置：

{
  "private": true,
  "dependencies": {
    "@yamato-daiwa/es-extensions": "1.5.1",
    "@yamato-daiwa/es-extensions-localization-japanese": "1.5.0-alpha.0"
  }
}

版本不匹配异常状态 #

如果用户误安装@yamato-daiwa/es-extensions@1.5.0，npm会在node_modules/@yamato-daiwa/es-extensions-localization-japanese/node_modules路径下额外嵌套安装一份1.5.1版本的核心依赖，形成两份核心包实例，对应目录结构：

该场景下不会抛出任何安装、运行时错误，但本地化功能会直接静默失效，问题隐蔽性极强，常规排查手段很难定位根因。

问题结论 #

仅将peerDependencies调整为固定版本"@yamato-daiwa/es-extensions": "1.5.1"，不足以完全解决问题。
从npm v7开始，虽然包管理器会自动安装peerDependencies，但如果用户已在项目中显式声明了不符合版本要求的核心包，npm仅会抛出警告，不会强制中断安装；yarn、pnpm等主流包管理器默认逻辑一致，依然可能出现依赖嵌套、多实例的问题。

可行修复方案 #

• 移除核心包在dependencies中的声明，仅保留peerDependencies依赖要求
  把@yamato-daiwa/es-extensions从dependencies配置中删除，仅在peerDependencies中声明版本要求，同时通过peerDependenciesMeta标记为必选依赖，从根源上避免包管理器在版本不匹配时自动嵌套安装依赖副本，消除多实例可能。参考配置：

  {
    "name": "@yamato-daiwa/es-extensions-localization-japanese",
    "version": "1.5.0-alpha.0",
    "peerDependencies": {
      "@yamato-daiwa/es-extensions": "1.5.1"
    },
    "peerDependenciesMeta": {
      "@yamato-daiwa/es-extensions": {
        "optional": false
      }
    }
  }
  

• 增加入口运行时版本校验，版本不匹配直接抛出明确错误
  在本地化包的入口文件最顶部增加版本校验逻辑，检测到核心包版本不符合要求时，直接抛出带明确修复指引的错误，避免功能静默失效。参考代码：

  import { version as coreVersion } from "@yamato-daiwa/es-extensions";
  const REQUIRED_CORE_VERSION = "1.5.1";
  if (coreVersion !== REQUIRED_CORE_VERSION) {
    throw new Error(
      `@yamato-daiwa/es-extensions-localization-japanese@1.5.0-alpha.0 仅兼容 @yamato-daiwa/es-extensions@${REQUIRED_CORE_VERSION}，当前检测到的核心包版本为${coreVersion}，请调整依赖版本至匹配版本后重试。`
    );
  }
  

• 文档明确标注版本对应关系
  在包的README等公开文档中明确标注每个本地化版本对应的核心包版本，同时给出不同包管理器下锁定核心包版本的配置参考（npm overrides、yarn resolutions、pnpm overrides），方便用户主动对齐版本。

内容的提问来源于stack exchange，提问作者Takeshi Tokugawa YD