依赖匹配机制
comp-hub 通过智能依赖匹配，让组件能够适配不同的本地环境。
为什么需要依赖匹配
组件在本地预览时，需要加载本地项目中已安装的依赖。但实际情况往往是：
- 组件依赖 echarts 5.2.0
- 本地安装的是 echarts 5.0.0
如果严格要求版本完全一致，会导致大量组件无法正常预览。因此平台提供了灵活的依赖匹配规则。
匹配规则
在「设置 > 依赖设置」中，可以为每个依赖库配置匹配规则：
| 规则 | 说明 | 适用场景 |
|---|---|---|
| 仅安装 | 只要本地安装了该依赖，不论版本 | 快速预览，非生产环境 |
| 主版本 | 主版本号相同即可 | 推荐，平衡兼容性和稳定性 |
| 主次版本 | 主次版本号都相同 | 对版本较敏感的场景 |
| 完全一致 | 版本号完全相同 | 严格版本控制 |
示例
假设组件依赖 echarts: 5.2.3：
| 本地版本 | 仅安装 | 主版本 | 主次版本 | 完全一致 |
|---|---|---|---|---|
| 5.0.0 | ✅ 使用 | ✅ 使用 | ❌ 跳过 | ❌ 跳过 |
| 5.2.0 | ✅ 使用 | ✅ 使用 | ❌ 跳过 | ❌ 跳过 |
| 5.2.3 | ✅ 使用 | ✅ 使用 | ✅ 使用 | ✅ 使用 |
| 6.0.0 | ✅ 使用 | ❌ 跳过 | ❌ 跳过 | ❌ 跳过 |
默认行为
- 未配置规则的依赖，默认采用主版本匹配
- Vue 框架强制使用主版本匹配（Vue 2 组件不会尝试在 Vue 3 项目中运行）
组件不显示的排查
当您在「推荐」列表中看不到某个组件时，可能是依赖不匹配导致的。按以下步骤排查：
1. 切换到「全部」筛选
在组件市场顶部切换筛选条件为「全部」，查看该组件是否显示。
2. 查看依赖状态
点击组件卡片，在预览页面查看依赖匹配状态：
- 🟢 绿色：依赖匹配成功
- 🔴 红色：依赖不匹配或缺失
- ⚠️ 黄色：依赖版本有差异但可尝试运行
3. 安装缺失依赖
如果提示依赖缺失，在本地项目中安装：
bash
npm install <package-name>安装完成后刷新页面。
4. 调整匹配规则
如果依赖版本有差异但不影响功能，可在「依赖设置」中放宽匹配规则。
最佳实践
组件作者
- 在
README.md中明确说明依赖要求 - 尽量使用兼容性较好的依赖版本
- 避免依赖特定的小版本特性
组件使用者
- 保持本地依赖版本较新，提高组件兼容性
- 对于非关键依赖，可使用「仅安装」或「主版本」匹配
- 遇到问题时优先查看控制台错误信息
常见问题
Q：为什么组件提示「缺少依赖」但本地已安装？
A：可能是：
- 依赖名称拼写不一致（如
echartsvsECharts） - 依赖安装在子目录的
node_modules中 - 需要刷新页面重新检测
Q：可以强制运行依赖不匹配的组件吗？
A：可以在「全部」列表中查看组件，但能否正常运行取决于实际的 API 差异。建议优先解决依赖问题。
Q：匹配规则对下载的组件有效吗？
A：匹配规则仅影响在线预览，下载的组件在您的项目中运行，使用的是您项目的依赖版本。