上傳與發布

這一頁說明把本地元件發布到平台的完整流程。第一次發布必須走這裡；之後的版本迭代見更新與版本。

上傳前檢查

• [ ] 元件是一個獨立資料夾，包含入口檔案（見元件規範）。
• [ ] 用到的依賴已經在目前專案的 node_modules 中。
• [ ] 單一檔案 ≤ 3 MB、總大小 ≤ 10 MB、檔案數 ≤ 30。
• [ ] 元件名稱符合 PascalCase 或 kebab-case，且沒有重名。
• [ ] 已準備 README.md，屬性與事件寫清楚了。

五步發布

1. 進入上傳頁

啟動本地服務後，左側選單點擊「上傳元件」。

2. 選擇元件目錄

左側檔案樹顯示設定檔中 dir 指定的目錄。導覽到元件資料夾並選取，點擊「選擇」。

3. 設定預覽

頁面上方是即時預覽，下方是設定區：

設定項	說明
小窗預覽	列表卡片裡展示的檔案，約定 demo/index.vue
全螢幕預覽	詳情頁展示的檔案，約定 demo/full.vue
元件依賴	從原始碼自動掃描，發布前核對是否有缺失
備註說明	一句話描述元件用途
附加資訊	更詳細的說明，支援搜尋關鍵字

Vue / React 選 .vue / .jsx / .tsx 檔案；Web Component 選 .html 檔案。

4. 產生設定

點擊「產生設定」，平台會寫入 comp.json：

{
  "__id__": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "MyComponent",
  "version": "1.0.0"
}

首次發布成功後，伺服器端會回寫 __id__。不要手動修改它，它是後續更新時識別元件的依據。

5. 發布

確認預覽與依賴無誤後，點擊「發布」。成功後元件會出現在「我的元件」，並按推薦規則進入元件市場。

框架是怎麼識別的

平台按以下順序逐條匹配，命中即止：

1. 存在 index.vue → Vue。
2. 存在 index.jsx / index.tsx → React。
3. 任一原始碼出現 customElements.define( 或 extends HTMLElement → Web Component。
4. 存在 index.js 且沒有註冊自訂元素 → React。
5. 都不命中 → 不給預設值，需要在上傳頁手動選擇。

上傳頁「附加資訊」裡的「元件框架」可以覆蓋識別結果，以介面選擇為準。

一個元件不要同時依賴 vue 和 react

否則無法判定框架，檢查與渲染都會失敗。

重複元件

平台會做相似度偵測。被判定為重複時：

• 不會進入「推薦」「熱門」「最新」列表。
• 只在「我的元件」中可見。
• 會出現在相似元件的推薦裡。
• 更新後同樣不享有推薦權重。

上傳前先搜尋是否已有同類元件，可以省掉一輪返工。

首次發布與更新的區別

	首次發布	後續更新
入口	上傳頁	更新頁或 comphub upload
是否建立元件	是，並寫入 __id__	否，只新增版本
是否可選預覽/描述	是	更新頁可以；CLI 不行
版本號	初始版本	改程式碼必須升版本

發布失敗排查

現象	原因	處理
提示缺少依賴	依賴沒裝在目前專案	在專案根目錄 npm install <pkg>
Component has no default export	React 入口只有具名匯出	改成 export default
Web Component 預覽報找不到 module script	HTML 裡沒有 <script type="module">，或寫在了 <head>	放進 <body>
預覽空白但終端機無報錯	資源路徑用了別名，或依賴版本跨大版本	改相對路徑、核對依賴
提示檔案超限	單一檔案 > 3 MB / 總量 > 10 MB / 數量 > 30	壓縮資源或拆分元件

下一步

• 繼續迭代版本：更新與版本
• 用命令列發布：使用 CLI
• 在瀏覽器裡從零開發並發布：使用 Studio