单例库要显式声明同一版本，否则运行时分裂

更新于 2026-07-25

**必须全局唯一的库（OTEL provider、React、状态容器等），只要有一个消费方没有显式声明版本，包管理器就会解出第二个版本，把整套 peer 依赖图复制一份 —— 结果是运行时出现两个 provider、注册与读取各走一份。**

案例（pnpm monorepo）

  • apps/ai-workflows 显式锁定 @opentelemetry/api@1.9.0，Agent 包没有直接声明 → pnpm 自动解到 1.9.1 → 整套 OTEL peer graph 被复制，pnpm-lock.yaml 多出约 259 行重复依赖。
  • 修法只有一个：给 Agent 也加上同样的精确版本，再重生成 lockfile。

判据与修法

信号含义
lockfile 里同一包出现两个版本、大段重复行依赖图被复制，单例前提已破
运行时「provider 分裂」类报错（追踪/上下文/状态取不到）往往就是两份实例
只在部分包里声明版本未声明的那份会被解析成「最近版本」

原则：需要单例的库，在所有消费方显式声明同一精确版本；不要依赖传递依赖「碰巧一致」。

相关