常見問題與術語

啟動與本地服務

連接埠被占用 / 改了連接埠沒生效

-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 要求是否一致。