常见问题与术语

启动与本地服务

端口被占用 / 改了端口没生效

-p 只在 master 未运行时生效。先 comphub kill，再 comphub -p 8080。

comphub 命令不存在

用 npx comp-hub，或全局安装后重开终端：npm install comp-hub@latest -g。

启动提示必须升级

执行 npm install comp-hub@latest -g，然后重新启动。

终端一直刷日志

这是当前项目的服务日志。按 Ctrl+C 结束并注销项目，服务不会影响其他项目。

组件市场与预览

组件在推荐/最新/热门里找不到

前三类会过滤依赖不匹配的组件。切到「全部」确认，再按依赖匹配处理。

提示缺少依赖，但本地已经装了

依次检查：包名拼写、依赖是否装在子目录的 node_modules、是否需要刷新页面重新检测。

预览正常，下载后不能用

预览用平台匹配后的依赖，下载后用的是你项目的版本。对比 README 里的依赖要求，必要时升级本地包。

上传与发布

为什么我的组件不进公共列表

可能被判定为重复组件，或依赖状态不满足推荐条件。重复组件只在「我的组件」可见。

comp.json 可以手写吗

不建议。它由平台生成，__id__ 用于识别组件身份。手动改坏会导致更新时找不到组件。

上传时提示文件超限

单文件 ≤ 3 MB、总大小 ≤ 10 MB、文件数 ≤ 30。压缩静态资源或拆分组件。

React 组件报 no default export

入口必须 export default。只有具名导出时没有可渲染的组件。

版本与更新

CLI 上传被拒绝

本地版本不大于线上。抬高 comp.json 的 version；只改描述/预览配置请走更新页。

更新后旧版本还能用吗

能。平台保留历史版本，使用方可以继续下载旧版本。

提交超时了要重试吗

先到平台确认最新版本。已经更新就不要重试，避免产生重复版本。

Studio

预览白屏

先等依赖装完，再确认入口文件与 default export。Web Component 检查 HTML 里的 <script type="module"> 是否在 <body>。

AI 不响应

平台内置模型需要登录；自填 Key 需要确认 Key 与模型可用。

刷新后工作区空了

确认没有删除工作区。Studio 的数据按工作区存在本机浏览器 IndexedDB，不会跨设备同步。

终端命令被拦

终端只放行 npm install / npm i / npm add，其他命令不会执行。

错误信息速查

提示	含义	处理
comp-hub must be upgraded before it can start	当前 CLI 版本必须升级	重新安装最新版
Local version ... is the published version	CLI 上传没有抬版本	修改版本号
Component has no default export	React 入口缺少默认导出	改 export default
Proxy not found	请求没有命中代理规则	检查 proxy 配置与 /__proxy__ 路径
预览文件里没有找到 <script type="module">	Web Component 预览 HTML 缺模块脚本	在 <body> 内补上
缺少依赖 / dependency missing	本地未安装组件依赖	在项目根目录安装

术语

术语	含义
组件	一个包含入口文件与资源的文件夹，文件夹名即组件名
工作区	Studio 里一份独立的文件与对话快照
依赖匹配	决定本地依赖版本能否满足组件要求的规则
预编译	平台把依赖提前打包，供预览时直接加载
mini / full	列表卡片的小窗预览 / 详情页的全屏预览
comp.json	组件元信息：__id__、name、version
组件 ID	__id__ 的值，更新与导入时用来识别同一个组件
语义化版本	主版本.次版本.补丁版本，分别对应破坏性变更、新功能、修复

环境与限制

项目	限制
Node.js	16.0.0 及以上
npm	8.0.0 及以上
单文件大小	3 MB
组件总大小	10 MB
文件数量	30 个
组件名称	PascalCase 或 kebab-case，同空间唯一
标签数量	最多 5 个

还是没解决

按这个顺序收集信息，能快速定位：

1. 终端的完整报错（不是最后一行的摘要）。
2. 浏览器控制台的第一条错误。
3. 组件的框架与入口文件名。
4. 本地依赖版本与 README 要求是否一致。