更新與版本

這一頁說明元件發布之後怎麼改、怎麼發新版本，以及版本號什麼時候必須動。

兩條更新路徑

路徑	適合	能改什麼
更新頁（Web）	首次發布之後的常規迭代	程式碼、預覽設定、描述、標籤
comphub upload	只改程式碼、想跳過頁面操作	只發布程式碼，不碰中繼資訊

首次發布仍然只能走上傳頁，因為 __id__ 是那一步寫入的。

用更新頁

1. 下載目前版本：在「我的元件」裡找到元件，點擊「更新」，先下載線上版本作為基準。
2. 本地修改：在專案裡改程式碼、補文件。
3. 本地驗證：用本地服務預覽，確認原有功能沒有回歸。
4. 提交更新：回到更新頁，選擇修改後的資料夾，抬高版本號，按需調整預覽與描述，點擊「更新」。

僅修改描述、標籤或預覽設定時，不需要抬高版本號。

用 CLI 更新

comphub login                                  # 每台機器一次
cd src/components/MyComponent
comphub upload -m "修復 tooltip 定位"

也可以明確指定目錄：

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

與更新頁的區別：

• 必須抬高版本號：本地 comp.json 的 version 不大於線上時，CLI 直接拒絕。
• 不碰描述、標籤、預覽設定：這些只能走更新頁。

提交前可以先空跑一次：

comphub upload -m "修復 tooltip 定位" --dry-run

--dry-run 會列印專案路徑、元件 ID、線上版本與將要發布的版本，然後停止，不提交。

語意化版本

主版本.次版本.修補版本

類型	變更	範例
修補	修 bug，向後相容	1.0.0 → 1.0.1
次版本	新增功能，向後相容	1.0.0 → 1.1.0
主版本	破壞性變更	1.0.0 → 2.0.0

必須升版本：改了元件程式碼、props 介面或行為邏輯。

可以不升：只改描述、標籤、預覽設定。

修改版本號的兩種方式

更新頁：在設定區直接改版本號輸入框，平台會同步寫入 comp.json。

本地手動改：

{
  "name": "MyComponent",
  "version": "1.1.0"
}

改完記得儲存，CLI 讀取的就是這個檔案。

多版本並存

平台保留歷史版本。使用者可以：

• 在預覽頁切換版本查看差異。
• 下載任意歷史版本。
• 在自己的專案裡鎖定使用的版本。

已下載的舊版本不會因為新版本發布而自動變化。

變更日誌

建議在 README.md 裡維護：

## 更新日誌

### 1.1.0 (2026-10-26)

- 新增：支援自訂主題色
- 最佳化：大資料量下的渲染效能

### 1.0.1 (2026-10-20)

- 修復：某些情況下 tooltip 不顯示

使用方看 README 比看版本號更能判斷要不要升級。

提交結果不確定時

如果 CLI 報 Submit result cannot be confirmed 或逾時，伺服器端可能已經寫入。不要直接重試，先到平台的元件詳情頁確認最新版本：

• 版本已更新：無需重試。
• 版本沒變：再執行一次上傳。

下一步

• 命令列完整說明：使用 CLI
• 更新時遇到報錯：常見問題