Docker构建报TS2322：BN无法赋值给含BN联合类型问题排查

这类「某类型无法赋值给显式包含该类型的联合类型」的报错，核心原因只有一个：报错位置两边的同名BN类型，在TypeScript的类型系统里根本不是同一个类型实体，哪怕结构完全一致，只要来源不同就会被判定为不兼容。结合提到的仅个别设备复现、本地和流水线构建正常的特征，优先从以下几个高频方向排查：

• 依赖多版本重复安装
  这是该类问题最高发的诱因。bn.js作为常用的大数处理库，很可能被多个上游依赖间接引入不同版本，如果正常构建的环境通过版本拍平、锁文件约束把所有bn.js/@types/bn.js对齐到了同一个版本，而异常设备因为锁文件未同步、使用的包管理器（npm/yarn/pnpm）版本和团队不一致、安装时加了额外参数，导致node_modules里同时存在多份独立的bn.js或其类型声明包：代码里导入的BN来自A路径下的包，联合类型定义里的BN来自B路径下的包，TS会直接判定二者不兼容。
  排查时直接在异常设备上执行包管理器的依赖列表命令查看重复版本即可：npm执行npm ls bn.js && npm ls @types/bn.js，pnpm执行pnpm ls bn.js -r，如果输出里出现两个及以上版本的相关包，先通过统一锁文件、配置包管理器版本强制拍平依赖再试。
• 全局类型声明冲突
  如果异常设备全局安装过@types/bn.js，或者项目的tsconfig.json没有正确配置typeRoots字段，TS会自动加载全局环境下的类型声明，此时全局的BN类型和项目内node_modules里的BN类型会被识别为两个独立类型，哪怕版本号完全一致也会触发兼容报错。
• TypeScript版本不一致
  如果异常设备没有使用项目内锁定的TS版本，而是调用了全局安装的、版本号和项目要求不一致的TSC进行编译，部分旧版本TS对类实例类型、跨模块导入类型的结构兼容性判定存在已知bug，会错误判定同结构类型不兼容。排查时直接在异常设备执行npx tsc -v，和正常构建环境的TS版本做比对即可确认。
• 软链接/Monorepo路径映射错位
  如果是Monorepo架构项目，异常设备如果通过npm link、软链接的方式调试其他本地包，TS解析类型时会顺着软链接走到被调试包自身的node_modules目录下查找BN类型，和当前项目根目录node_modules下的BN类型形成两份独立声明，也会触发该报错。

快速验证方法：在异常设备上用IDE打开报错文件，分别悬停在报错位置左右两边的BN类型上，查看弹出的类型定义来源路径，如果两个路径不是同一个文件，即可确认是上述多类型副本问题，和业务代码逻辑无关。

内容的提问来源于stack exchange，提问作者Eric