组件上传指南

将组件上传到 comp-hub 只需三步：选择文件夹、配置预览、点击发布。

前置要求

上传前请确保组件满足以下条件：

文件夹形式：组件必须以文件夹形式存在，文件夹名称即为组件名称
入口文件：必须有入口文件 —— Vue 组件为 index.vue，React 组件为 index.jsx / index.js / index.tsx
独立可运行：组件应是自包含的，依赖通过相对路径引入

推荐的目录结构：

MyComponent/           # 组件名称
├── index.vue         # 入口文件（必需）
├── README.md         # 组件文档（建议）
├── comp.json         # 配置文件（自动生成）
└── assets/           # 静态资源（如有）
    └── logo.png

上传限制

上传组件时需遵守以下限制：

限制项	说明
单文件大小	单个文件不超过 3MB。大文件（如音频、视频、高分辨率图片）请先压缩再上传
总大小	组件所有文件总大小不超过 10MB
文件数量	组件文件（含子目录）总数不超过 30 个

如果提交时提示文件大小超出限制，请检查是否有过大的静态资源文件，压缩或移除后再试。

UI 框架支持

组件预览支持 Vue 和 React 两种框架，各自生态下的 UI 框架均可直接使用。

框架如何识别

框架不需要在任何地方声明，comp-hub 会根据组件源码中扫描到的依赖自动判定：

组件引入了 vue → 判定为 Vue 组件
组件引入了 react → 判定为 React 组件
同时引入 vue 和 react → 无法判定框架，上传页将无法检查与渲染该组件

Vue 组件

对于 Vue 组件，在组件根目录添加 main.js 文件，引入并注册 UI 框架即可：

Vue 2

import Vue from 'vue';
import Antd from 'ant-design-vue';
import 'ant-design-vue/dist/antd.css';
Vue.use(Antd);

Vue 3

注意：Vue 3 默认不导出 app 实例。此处的 Vue.app 由工具内部创建并挂载到 Vue 上，与官方自行调用 createApp() 的方式不同，直接使用即可。

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

Vue.app.use(ArcoVue);

React 组件

React 组件无需 main.js 文件，依赖也不是在 comp.json 中声明 —— 直接在组件里正常 import 即可：

jsx

import { Button, Card } from "antd";
import { LikeOutlined } from "@ant-design/icons";

export default function MyCard() {
  return <Card>Hello</Card>;
}

在上传页选中组件文件夹后，comp-hub 会扫描源码中的 import 语句，从本地项目的 node_modules 中解析每个依赖并预编译，供预览使用。因此：

组件用到的依赖必须已在本地项目中安装（npm install <pkg>），否则预览会提示依赖缺失
扫描到的依赖及版本会显示在配置区的「组件依赖」Tab 中，发布前可核对
入口文件必须有 default export，仅有具名导出会报 Component has no default export
同时支持 React 18（react-dom/client）与 React 17（react-dom），渲染 API 会自动适配

命名规范

组件名称在同一空间内唯一（公共平台，或某个团队内），不能与已有组件重名
仅支持两种格式：PascalCase（UserGrowthChart）或 kebab-case（alipay-data-table）
不支持下划线 _、camelCase（myComponent），也不能以数字开头
建议采用前缀命名法，如 公司名-业务域-组件名：alipay-data-table

重复组件处理

平台会对上传的组件进行相似度检测。若被判定为重复组件：

不会进入「推荐」「热门」「最新」等公共列表
仅可在「我的组件」中查看和管理
会出现在相似组件的推荐列表中
更新时同样不享受推荐权重

建议在上传前检查是否已有功能相似的组件，避免重复造轮子。

上传步骤

1. 进入上传页面

启动 comp-hub 后，在左侧菜单点击「上传组件」。

2. 选择组件

左侧文件树显示 .comphub.json 或 .comphub.js 中 dir 指定的目录
导航到组件所在文件夹并选中
点击「选择」确认

3. 配置预览

上传页面分为上下两个区域：

上方预览区

实时展示组件渲染效果
支持刷新和切换背景色

下方配置区

小窗预览：选择用于列表页展示的文件，约定为 demo/index.vue（也可以是组件入口本身）
全屏预览：选择用于详情页展示的文件，约定为 demo/full.vue（建议配置）
组件依赖：从源码自动扫描出的依赖及其本地版本，可在此核对
备注说明：简短描述组件功能和适用场景
附加信息：详细描述，支持搜索关键词

组件文件夹内任意以 .vue、.jsx、.tsx 结尾的文件都可以选作预览文件，demo/ 目录只是约定而非强制。React 组件请使用 .jsx / .tsx 文件。

4. 生成配置

点击「生成配置」按钮，系统会自动创建 comp.json 文件，包含：

json

{
  "__id__": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "MyComponent",
  "version": "1.0.0"
}

comp.json 只有这三个字段。首次发布成功后服务端会写入 __id__，请勿手动修改。依赖来自源码扫描，不写在这个文件里。

5. 发布组件

确认配置无误后，点击「发布」按钮完成上传。

最小化示例

以下是一个最简单的可上传组件：

vue

<!-- MyButton/index.vue -->
<template>
  <button class="my-button" @click="handleClick">
    {{ text }}
  </button>
</template>

<script>
export default {
  name: 'MyButton',
  props: {
    text: {
      type: String,
      default: '点击我'
    }
  },
  methods: {
    handleClick() {
      this.$emit('click')
    }
  }
}
</script>

<style scoped>
.my-button {
  padding: 8px 16px;
  background: #409eff;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
</style>

最小 React 示例

jsx

// MyCard/index.jsx
import { Card } from "antd";

export default function MyCard({ title = "Hello" }) {
  return <Card>{title}</Card>;
}

antd 需在本地项目中已安装；default export 是必须的。

最佳实践

编写 README：详细说明组件用途、属性、事件和示例
提供 Demo：创建 demo 目录，展示组件的典型用法
语义化版本：遵循 主版本.次版本.补丁版本 规范
处理依赖：第三方依赖在本地安装即可，无需打包到组件中

组件上传指南 ​

前置要求 ​

上传限制 ​

UI 框架支持 ​

框架如何识别 ​

Vue 组件 ​

Vue 2 ​

Vue 3 ​

React 组件 ​

命名规范 ​

重复组件处理 ​

上传步骤 ​

1. 进入上传页面 ​

2. 选择组件 ​

3. 配置预览 ​

4. 生成配置 ​

5. 发布组件 ​

最小化示例 ​

最小 React 示例 ​

最佳实践 ​