Angular库中可选peerDependencies的正确用法及模块找不到报错解决

问题描述 #

我开发了一个包含多个独立组件的Angular库，部分组件依赖第三方库（如angular2-draggable、@fortawesome/angular-fontawesome等）。我的需求是消费应用仅引入实际用到的组件对应的依赖——比如库中有Foo和Bar两个组件，Bar依赖angular2-draggable，如果应用只用到Foo，就不需要安装angular2-draggable。

我尝试将angular2-draggable配置为可选peer依赖，package.json配置如下：

"sideEffects": false,
"peerDependencies": {
  "angular2-draggable": "^16.0.0"
},
"peerDependenciesMeta": {
  "angular2-draggable": {
    "optional": true
  }
}

库能正常构建发布，安装也没问题，但应用启动时还是报错：

Error: Module not found: Error: Can't resolve 'angular2-draggable'

哪怕完全没使用Bar组件也会出现这个错误。请问怎么才能确保只引入必要的依赖？

核心问题分析 #

你当前的配置只是声明了依赖是可选的，但Bar组件的代码里直接引入了angular2-draggable，打包工具（比如Webpack）在分析依赖树时，只要Bar组件的模块被包含在库的入口或共享模块里，就会尝试解析这个依赖，哪怕应用没用到Bar。

具体解决步骤 #

1. 拆分组件为独立的NgModule/入口 #

把每个组件（包括依赖第三方库的组件）拆成单独的NgModule，并且在库的package.json里为每个组件配置独立的入口。比如：

"exports": {
  "./foo": "./dist/foo/index.js",
  "./bar": "./dist/bar/index.js"
}

这样消费应用可以直接引入单个组件：import { FooModule } from 'your-lib/foo'，而不是引入整个库的根模块。

2. 确保Tree Shaking完全生效 #

除了sideEffects: false，还要确认：

• 库的tsconfig.lib.json里module字段设置为ESNext或ES2020，保证输出ES模块格式的代码
• 消费应用的生产环境构建默认开启Tree Shaking，开发环境可通过调整Angular CLI配置强制开启

3. 为子组件单独配置依赖范围 #

不要把所有可选依赖都放在根package.json里，而是为每个组件子目录单独配置package.json，把对应的依赖声明在子模块的peerDependencies里。比如Bar组件的子目录package.json：

"peerDependencies": {
  "angular2-draggable": "^16.0.0"
},
"peerDependenciesMeta": {
  "angular2-draggable": {
    "optional": true
  }
}

4. 动态导入第三方依赖（可选） #

如果无法拆分模块，可在Bar组件代码里用动态导入避免强制依赖（注意模板语法的局限性，仅适合逻辑层依赖）：

import { Component, OnInit } from '@angular/core';

@Component({...})
export class BarComponent implements OnInit {
  async ngOnInit() {
    const { DraggableDirective } = await import('angular2-draggable');
    // 按需使用导入的依赖
  }
}

验证方法 #

配置完成后，消费应用只引入Foo组件，执行npm ls angular2-draggable，如果输出里没有该依赖，说明配置生效；同时启动应用不会再出现模块找不到的错误。

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