使用 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