使用 CLI

CLI 负责三件事：启动本地服务、管理运行中的项目、在终端发布组件更新。三个二进制名 comphub、ch、comp-hub 指向同一个程序。

命令总览

命令	作用
comphub	启动当前项目的本地服务
comphub status	查看 master 状态与所有运行中的项目
comphub stop <hash>	停止指定项目
comphub stop --all	停止所有项目
comphub kill	关闭 master 与全部项目
comphub fix	清理残留运行时文件
comphub login	浏览器授权登录并保存凭据
comphub upload [compDir]	为已发布组件发布新版本
comphub install <组件名[@版本]>	下载已发布的公开组件到当前目录

启动服务

comphub

参数：

参数	简写	默认值	说明
--port	-p	5478	服务端口
--dir	-d	./	组件根目录
--log-level	-l	error	debug / info / warn / error
--version	-v	—	显示版本
--help	-h	—	显示帮助

comphub -p 8080
comphub -d ./src
comphub -l debug

端口参数只在 master 未运行时生效

已有服务在跑时，CLI 会复用原端口并提示 -p 被忽略。需要换端口先执行 comphub kill。

启动后终端会打印：

Version  0.44.11
Project  D:\project\my-app
Hash     94525912
Port     5478
URL      http://localhost:5478/94525912/main/

Hash 是当前目录的标识，stop 命令要用它。按 Ctrl+C 结束当前项目的日志输出，并自动注销该项目。

配置文件

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

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

配置项	类型	默认值	说明
dir	string	./	组件根目录，上传/下载只能操作该目录及其子目录
allowDebug	boolean	false	是否允许调试模式
proxy	object	—	代理规则，格式同 http-proxy-middleware

.comphub.js 按项目的模块系统导出：

// CommonJS
module.exports = { dir: "./src" };

// ESM（package.json 有 "type": "module"）
export default { dir: "./src" };

加载顺序：.comphub.json → .comphub.js → 默认值。配置优先级：命令行参数 > 配置文件 > 默认值。

代理规则

组件 demo 跑在 iframe 里，只能访问本地服务。需要请求内网后端或没有 CORS 头的接口时，用 proxy 转发：

{
  "proxy": {
    "/api": {
      "target": "http://10.0.0.5:8080",
      "changeOrigin": true,
      "pathRewrite": { "^/api": "" }
    }
  }
}

demo 里这样请求：

fetch("/__proxy__/api/users");

规则说明：

• key 匹配 /__proxy__ 之后的路径，支持前缀或正则。
• 值原样交给 http-proxy-middleware，target 必填。
• pathRewrite 在剥掉 /__proxy__ 前缀后生效。
• 没有命中规则时返回 404 {"message":"Proxy not found"}。
• 规则只对声明它的项目生效。

查看与停止

comphub status          # 查看 master 与项目列表
comphub stop 94525912   # 停止指定项目
comphub stop --all      # 停止全部项目
comphub kill            # 关闭 master 与所有项目
comphub fix             # 清理残留运行时文件

status 会列出每个项目的 hash、路径与访问地址。fix 用于上次异常退出留下残留文件、导致启动失败的情况。

登录

comphub login

CLI 会申请一次授权并打开浏览器页面，你在页面上确认后，凭据保存到 ~/.comphub/credentials.json。每台机器只需要登录一次。

comphub login --no-browser   # 只打印授权地址

授权会话是一次性的：等待授权的会话 2 分钟过期，CLI 最多等 5 分钟。凭据失效时重新执行 comphub login。

发布新版本

comphub upload 只用于已经发布过的组件。首次发布走上传与发布。

cd src/components/MyComponent
comphub upload -m "修复 tooltip 定位"

参数	简写	说明
--message	-m	升级说明，必填
--dry-run	—	只校验并打印内容，不提交
--dir	-d	资源目录，含义同启动参数

执行时 CLI 会：

1. 定位组件所属项目。
2. 确保该项目有本地服务（没有就起一个）。
3. 提交组件目录，服务端做校验、依赖预编译与上传。

提交可能持续几分钟，CLI 给了 10 分钟超时。

版本号必须大于线上

本地 comp.json 的 version 不大于线上时，CLI 直接拒绝。修改代码后先抬版本号再上传。只改描述或预览配置请走更新页。

安装组件

comphub install 下载一个已发布的公开组件源码 zip，并解压到当前目录。

comphub install ThemeSwitch
comphub install ThemeSwitch@1.0.0
comphub install ThemeSwitch --force

参数	简写	说明
<组件名>	—	必填；必须是已发布的公开组件
@版本	—	可选；不写则安装最新版本
--force	-f	./<组件名>/ 已存在时替换
--remote	—	远端服务地址，含义同其他命令

执行时 CLI 会：

1. 在公开组件里按名称精确查找。
2. 下载源码 zip（小包直连，大包走 OSS 签名地址）。
3. 剥掉 zip 里的 组件名_版本/ 顶层目录，解压到当前目录的 ./<组件名>/。

不需要登录，也不需要本地服务。组件依赖不会自动安装，按组件 README 自行处理。

ThemeSwitch/
├── index.vue        # React 为 index.jsx / index.tsx
├── comp.json
├── README.md
└── demo/

--force 会替换整个目录

新包解压成功后才会删除旧目录；如果最后一步替换失败，旧目录无法恢复。执行前先提交本地改动。

常见错误：

• 找不到组件：只能安装已发布的公开组件；有相近名称时 CLI 会列出候选。
• 版本不存在：CLI 会打印线上最新版本。
• 目标已存在：加 --force 才会替换。

多项目并行

不同项目可以同时启动，各自分配独立端口：

# 终端 1
cd /path/to/project-a && comphub

# 终端 2
cd /path/to/project-b && comphub

comphub status

常见问题

启动提示必须升级

按提示执行 npm install comp-hub@latest -g 后重新启动。

上传报版本号错误

本地版本不大于线上。抬高 comp.json 的 version，或改用更新页提交元信息。

提交超时 / 结果无法确认

不要直接重试。先到平台确认最新版本是否已更新，再决定是否重发。

start 后浏览器打不开

确认访问的是终端打印的完整 URL（包含 /{hash}/main/），而不是裸端口。

下一步

• 第一次发布：上传与发布
• 浏览器里开发组件：使用 Studio