comp-hub：让你的 Vue 业务组件真正"活"起来

comp-hub：让你的 Vue 业务组件真正"活"起来

一个能"先跑起来再看文档"的 Vue 业务组件共享平台，正在重新定义团队组件复用的方式。

---

写在前面

你有没有经历过这些场景？

• 新项目需要一个图表组件，记得上个项目写过类似的，翻遍 Git 历史也没找到
• 从别的项目复制来一个表格组件，改了半小时路径和样式，最后发现还有依赖没装
• 封装了一个很棒的组件，但同事压根不知道它的存在，又重写了一个
• 接手新项目，发现里面有三个功能类似的"用户选择器"，但各自都有点问题

如果你也曾为"找个组件"或"复制组件"浪费过时间，那么这篇文章正是为你写的。

今天要介绍的 comp-hub，是一个面向 Vue 技术栈的组件预览与共享平台。它用一个核心理念颠覆了传统的组件复用方式：

能马上跑起来的组件，才有阅读和了解的价值。

---

传统组件复用为什么这么难？

当前开发者找组件的典型流程是这样的：

搜索 → 看 README → 觉得不错 → 装依赖 → 跑不起来 → 换一个 → 再看 README → 又跑不起来 → 放弃，自己写

你投入了大量精力阅读文档、理解 API，最后发现它跟你的项目技术栈根本不兼容------这个过程中浪费的不仅是时间，更是心力和信任。

comp-hub 把这个流程颠倒了过来：

打开平台 → 自动过滤不兼容的组件 → 剩下的全部能跑 → 直接看效果 → 满意就下载，直接用

"能不能跑"这个判断被前置了，而不是让用户投入时间阅读之后才发现用不了。这是一个看似简单、实则深远的思路转变。

---

comp-hub 是什么？

comp-hub 是一个集在线预览、智能依赖匹配、一键下载、版本管理于一体的 Vue 业务组件共享平台。

它的核心流程只有三步：

1. 上传：写好组件，一键上传，自动提取依赖和元数据
2. 预览：在线查看组件实际运行效果，支持小窗/全屏切换
3. 下载 ：满意就下载到项目 components 目录，直接 import 使用

目前 comp-hub 已经发布到 npm，版本 v0.28.4，支持 Vue 2.x 和 Vue 3.x，React 支持在规划中。

---

五大核心能力

1. 实时预览：所见即所得

打开组件详情页，你会同时看到：

• 上方：真正在运行的组件实例------一个在你的本地环境中渲染的、可交互的组件
• 下方：完整的 README 文档------属性、事件、插槽、示例一应俱全

一个页面同时解决"看效果"和"看文档"两件事。更重要的是，这个预览是在你的本地项目中渲染的，使用的是你项目真实安装的依赖版本，而不是某个服务器上"不知道用什么环境跑起来"的截图。

缩放与居中 API

为了让组件在预览面板中完美适配，comp-hub 还提供了两个特殊方法：

• $getScaleStyle ：主动获取缩放+居中样式，支持 contain（等比例适配）、cover（填满裁切）、widthFirst（宽度优先）、heightFirst（高度优先）四种模式
• $onScaleChange：订阅容器尺寸变化，自动回调最新样式

<template>
  <div class="demo-wrapper" :style="scaleStyle">
    <div class="demo-content">
      <!-- 按照 800×500 设计的内容 -->
    </div>
  </div>
</template>

<script>
export default {
  data() {
    return { scaleStyle: {} }
  },
  mounted() {
    this._unsub = this.$onScaleChange(
      { mode: "contain", width: 800, height: 500 },
      (style) => { this.scaleStyle = style }
    )
  },
  beforeDestroy() {
    this._unsub?.()
  }
}
</script>

2. 智能依赖匹配：让组件适配你的项目

这是 comp-hub 最核心的差异化功能。

组件在本地预览时，需要加载你项目中已安装的依赖。但实际情况往往是：

• 组件依赖 echarts 5.2.0
• 你本地安装的是 echarts 5.0.0

如果严格要求版本一致，大量组件将无法预览。因此 comp-hub 提供了四级灵活匹配：

匹配规则	说明	严格程度
🟢 仅安装	只要安装了该依赖，不论版本	最宽松
🔵 主版本	主版本号相同即可（推荐）	平衡
🟠 主次版本	主次版本号都相同	较严格
🔴 完全一致	版本号完全相同	最严格

以 echarts 5.2.3 为例：

你本地版本	仅安装	主版本	主次版本	完全一致
5.0.0	✅ 可用	✅ 可用	❌ 跳过	❌ 跳过
5.2.0	✅ 可用	✅ 可用	❌ 跳过	❌ 跳过
5.2.3	✅ 可用	✅ 可用	✅ 可用	✅ 可用
6.0.0	✅ 可用	❌ 跳过	❌ 跳过	❌ 跳过

默认采用"主版本"匹配，Vue 框架强制主版本匹配（Vue 2 组件不会尝试在 Vue 3 项目中运行），兼顾了兼容性和可用性。

匹配规则仅在在线预览阶段生效------下载后的组件在你的项目中运行，自然使用你项目的依赖版本。

3. 一键上传：三步完成发布

上传一个组件到 comp-hub，只需要：

1. 选择文件夹 ：组件必须是文件夹形式，包含 index.vue 作为入口文件
2. 配置预览 ：选择小窗预览（demo/index.vue）和全屏预览（demo/full.vue），写点备注说明
3. 点击发布 ：系统自动生成 comp.json，上传完成

推荐的目录结构：

MyComponent/           # 组件名称
├── index.vue         # 入口文件（必需）
├── README.md         # 组件文档（建议）
├── comp.json         # 配置文件（自动生成）
├── demo/
│   ├── index.vue     # 小窗预览示例
│   └── full.vue      # 全屏预览示例
└── assets/           # 静态资源（如有）
    └── logo.png

这里有一个关键的设计理念：组件必须是自包含的 。也就是说，组件运行所需的所有文件（.vue、.js、图片、样式等）都要放在组件文件夹内，引用时使用相对路径：

<script>
// ✅ 正确：相对路径引用
import bgIcon from './assets/bg.png'
import utils from './utils.js'

// ❌ 错误：路径别名（@、~ 等），换个项目就找不到了
import bgIcon from '@/assets/bg.png'
</script>

第三方 npm 依赖（如 echarts、lodash 等）则不需要打包进组件------上传时系统会自动扫描 import 语句提取依赖信息，下载后在你的项目里直接用本地已安装的版本即可。这个设计让组件体积极小，同时又能适配不同项目的依赖环境。

对于使用 Element Plus、Ant Design、Arco Design 等 UI 框架的项目，只需在组件根目录添加 main.js 注册即可：

// Vue 3 示例
import * as Vue from 'vue'
import ArcoVue from '@arco-design/web-vue'
import '@arco-design/web-vue/dist/arco.css'

Vue.app.use(ArcoVue)

上传限制也值得一提：单文件 ≤ 3MB，总大小 ≤ 10MB，文件数 ≤ 30 个------这些约束确保了组件保持轻量、可移植。

4. 版本管理：多版本并存与切换

comp-hub 遵循语义化版本 规范（主版本.次版本.补丁版本），平台保留所有历史版本。

更新流程也很自然：

下载组件 → 本地修改 → 测试验证 → 上传更新

在预览页面随时可以切换查看不同版本，也可以下载任意历史版本。这比"代码复制粘贴然后各自改"的方式可控得多。

5. 组件市场：发现与复用

组件市场提供四种筛选视图：

• 推荐：根据使用量和评分智能推荐
• 最新：按发布时间倒序
• 热门：按下载量排序
• 全部：显示所有组件（包括依赖不匹配的，用"全部"可以发现被依赖过滤掉的组件）

---

5 分钟快速上手

安装

# 全局安装（推荐）
npm install comp-hub@latest -g

# 或在项目中本地安装
npm install comp-hub@latest -D

启动

# 在项目目录下执行
comphub

启动成功后，终端会显示类似输出：

✓ comp-hub v0.28.4
✓ Project registered

  URL      http://localhost:5478/xxxxxxx/main/

  comphub status               查看所有运行中项目
  comphub stop    xxxxxxx      停止当前项目
  comphub stop    --all        停止所有项目
  comphub kill                 关闭全部服务

用浏览器打开显示的 URL，就可以开始使用了。

配置

在项目根目录创建 .comphub.json：

{
  "dir": "./src",
  "allowDebug": false
}

dir 指定了组件代码的根目录，上传和下载只能在该目录及其子目录中进行------这是一个安全边界设计。

---

一个完整示例：ECharts 图表组件的上传与复用

假设你开发了一个用户增长趋势图表组件 UserGrowthChart，依赖 echarts。

组件代码

<!-- UserGrowthChart/index.vue -->
<template>
  <div class="chart-container">
    <h3 class="chart-title">{{ title }}</h3>
    <div ref="chartRef" class="chart"></div>
  </div>
</template>

<script>
import * as echarts from 'echarts'

export default {
  name: 'UserGrowthChart',
  props: {
    title: { type: String, default: '用户增长趋势' },
    data: { type: Array, required: true }
  },
  mounted() {
    this.chart = echarts.init(this.$refs.chartRef)
    this.chart.setOption({
      xAxis: { type: 'category', data: this.data.map(d => d.date) },
      yAxis: { type: 'value' },
      series: [{
        data: this.data.map(d => d.value),
        type: 'line',
        smooth: true
      }]
    })
  },
  beforeDestroy() {
    this.chart?.dispose()
  }
}
</script>

写好 README

# UserGrowthChart 用户增长图表

展示用户增长趋势的折线图组件，基于 ECharts 实现。

## 属性

| 属性名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| title | String | 否 | 图表标题 |
| data | Array | 是 | 格式 [{ date: '2024-01', value: 100 }] |

## 依赖

- echarts: ^5.0.0

上传

在 comp-hub 中选中 UserGrowthChart 文件夹，配置小窗和全屏预览，点击发布------完成。

复用

其他同事在 comp-hub 中搜索到 UserGrowthChart，预览效果满意，一键下载到项目：

<template>
  <UserGrowthChart
    title="月度活跃用户"
    :data="growthData"
    style="height: 400px"
  />
</template>

<script setup>
import UserGrowthChart from '@/components/UserGrowthChart/index.vue'

const growthData = [
  { date: '2024-01', value: 1200 },
  { date: '2024-02', value: 1500 },
  { date: '2024-03', value: 1800 }
]
</script>

整个流程不到一分钟，比复制粘贴代码然后修路径、调依赖快了不止一个数量级。

---

comp-hub 的架构亮点

如果你对底层实现感兴趣，这里有几个值得关注的架构设计：

iframe 隔离渲染

每个组件预览都运行在独立的 iframe 中，确保组件代码不会相互干扰。主应用通过 postMessage 与 iframe 通信，定义了 60+ 种消息类型，覆盖列表操作、组件预览、版本管理、主题切换等场景。

本地运行 + 云端存储

组件在你的本地环境中渲染------这意味着预览效果和最终使用效果完全一致。组件元数据和代码存储在云端，方便团队检索和共享。

开箱即用的依赖分析

上传时自动扫描组件的 import 语句，提取依赖信息，无需额外配置。下载时也无需关心依赖安装------你的项目有什么版本，下载的组件就用什么版本。

---

与其它方案对比

相较于 Monorepo

Monorepo 适合紧密协作的同一产品线 的大型团队。但它的前提是所有项目在同一个仓库，通常要求统一技术栈和构建工具。comp-hub 更适合松耦合的跨团队、跨项目组件共享------项目完全独立，零改造接入。

相较于发布到 npm

npm 适合发布公共基础库和通用组件。但对于业务组件------那些跟公司业务逻辑强相关、可能频繁迭代的组件------npm 的发布流程显得过重。comp-hub 提供了一键上传、即时预览、灵活版本管理的更轻量方案。

与 AI 的关系

有人可能问：AI 都能直接生成组件了，还需要 comp-hub 吗？

答案是：更需要了。

AI 生成组件很快，但如果生成的组件散落在各个项目中，很快又会变成"找不到、用不了"的状态。comp-hub 可以与 AI 完美配合：

• 用 AI 生成组件基础代码
• 在 comp-hub 上预览、调试、完善
• 上传保存，供团队复用

工具本身解决的是"创造速度"问题，comp-hub 解决的是"成果沉淀"问题，两者互补。

---

适用场景

场景	价值
前端团队	建立团队组件库，统一业务组件规范，避免重复开发
独立开发者	管理个人组件资产，跨项目复用
外包公司	快速复用历史项目组件，提升交付效率

---

写在最后

comp-hub 解决的不是一个"技术前沿"的问题，而是一个普遍的工程效率问题：如何让写好的组件被真正用起来？

它的答案也很朴素：让组件"先跑起来"，让效果"看得见"，让复用"零成本"。这个思路可以直接用在你们团队的组件管理上。

如果你对这个项目感兴趣，可以通过以下方式了解更多：

• 📖 官方文档: docs.comphub.cn/zh/
• 📦 npm: www.npmjs.com/package/com...
• 📧 联系作者: 1406059122@qq.com

---

如果你也被"组件找不到、用不了、重复造轮子"的问题困扰过，欢迎点赞、收藏、评论，让更多有同样困扰的开发者看到这个方案。