如何构建带peerDependencies的Angular库并解决依赖报错

Angular 库的peerDependencies设计规则是：作为库的依赖声明，要求库的最终使用方（即安装@myproject/auth的业务应用）必须自行安装对应版本的依赖，避免多版本冗余、全局服务/变量实例重复的问题。你遇到的两类报错本质是配置逻辑没有对齐开发构建和分发的不同要求：

• 将@myproject/utilities放入dependencies时，Angular 库构建器默认禁止同仓内部依赖作为普通依赖打包进产物，因此弹出提示要求迁移到peerDependencies或显式配置白名单
• 将@myproject/utilities放入peerDependencies时报TS2307错误，是因为npm ci执行时只会安装dependencies和devDependencies下的包，peerDependencies不会被自动安装，构建阶段找不到对应模块的类型和源码就会直接崩溃。

不要用allowedNonPeerDependencies绕开校验把依赖放在dependencies里，这种方式会导致最终打包的auth库自带一份utilities代码，和业务应用中直接安装的utilities形成多实例，极易引发服务重复初始化、全局状态冲突等隐性问题。按照以下步骤配置即可：

• 调整@myproject/auth的package.json配置，保留@myproject/utilities在peerDependencies中，同时将同版本的依赖加入devDependencies：

  {
    "peerDependencies": {
      "@angular/core": "^16.0.0", // 保留原有其他peer依赖
      "@myproject/utilities": "^1.0.0" // 版本号和你实际发布的版本对齐
    },
    "devDependencies": {
      "@myproject/utilities": "^1.0.0" // 版本和peerDependencies保持完全一致
    }
  }
  

  说明：devDependencies仅在当前库的开发、构建阶段生效，不会被写入最终分发的npm包依赖清单，不会影响使用方的依赖安装逻辑，完全符合npm包发布规范。

• 重新执行npm ci，此时npm会自动安装devDependencies下的@myproject/utilities，再执行ng build auth就不会出现模块找不到的错误，构建器也不会弹出dependencies配置不合规的提示。

这个配置的作用是告诉Angular构建器跳过指定依赖的peer校验，仅适合以下场景使用：

• 依赖是仅在构建阶段生效的polyfill、编译辅助工具，不会暴露给库的使用方
• 依赖是你确定会被打包进库产物、不需要使用方单独安装的第三方工具库

对于@myproject/utilities这类需要和业务应用共享实例的公共依赖，不推荐使用该选项绕开规则。如果你使用的是Nx等Monorepo管理工具，也可以通过根目录tsconfig.json配置路径映射直接指向utilities的源码目录，不需要额外在auth库的devDependencies中声明依赖，核心逻辑还是保证构建auth时可以解析到utilities的模块即可。

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