依賴匹配機制

comp-hub 使用智慧依賴匹配，讓元件能夠適應不同的本機環境。

為什麼需要依賴匹配

當元件在本機預覽時，需要載入本機專案中已安裝的依賴。但實際情況往往是：

• 元件依賴 echarts 5.2.0
• 本機安裝的是 echarts 5.0.0

如果要求嚴格版本一致，很多元件將無法正常預覽。因此，平台提供了靈活的依賴匹配規則。

匹配規則

在「設定 → 預覽規則」的依賴區塊中，可以為專案中的每個依賴（含 dependencies 與 devDependencies）設定匹配規則：

規則	說明	適用場景	顏色指示
自動	不做版本限制，使用目前本機環境渲染	預設值，盡量保證可渲染	⚪ 灰色（預設）
僅安裝	只要本機安裝了該依賴，不考慮版本	快速預覽、非生產環境	🟢 綠色（最寬鬆）
主版本	主版本號必須一致	兼顧相容性和穩定性	🔵 藍色
主版本.次版本	主版本和次版本號都必須一致	對版本敏感的場景	🟠 橘色（中度嚴格）
精確匹配	版本號必須完全一致	嚴格版本控制	🔴 紅色（最嚴格）

規則來源為專案的 package.json，依賴預編譯時同樣遵循這些規則。

提示：設定頁中的每個匹配規則前都有對應的彩色圓點指示，方便快速辨識匹配嚴格程度。

範例

假設元件依賴 echarts: 5.2.3：

本機版本	自動	僅安裝	主版本	主.次版本	精確匹配
5.0.0	✅ 使用	✅ 使用	✅ 使用	❌ 跳過	❌ 跳過
5.2.0	✅ 使用	✅ 使用	✅ 使用	❌ 跳過	❌ 跳過
5.2.3	✅ 使用	✅ 使用	✅ 使用	✅ 使用	✅ 使用
6.0.0	✅ 使用	✅ 使用	❌ 跳過	❌ 跳過	❌ 跳過
未安裝	❌ 跳過	❌ 跳過	❌ 跳過	❌ 跳過	❌ 跳過

預設行為

• 未手動設定規則的依賴預設採用自動（不做版本限制，使用目前本機環境渲染）
• 本機完全未安裝的依賴任何規則都不會匹配，需先安裝再重新整理
• 框架由元件自身依賴判定：引入 vue 以 Vue 渲染，引入 react 以 React 渲染（React 17 與 18 皆支援）；兩者都引入則無法渲染

排除元件不顯示的問題

當您在「推薦」列表中看不到某個元件時，可能是依賴不匹配造成的。請按照以下步驟排查：

1. 切換到「全部」篩選

將元件市場頂部的篩選條件切換為「全部」，看看元件是否顯示。

2. 檢查依賴狀態

點擊元件卡片，在預覽頁檢查依賴匹配狀態：

• 🟢 綠色：依賴匹配成功
• 🔴 紅色：依賴不匹配或缺失
• ⚠️ 黃色：依賴版本有差異但可嘗試執行

3. 安裝缺失的依賴

如果提示依賴缺失，請在本機專案中安裝：

npm install <package-name>

安裝後重新整理頁面。

4. 調整匹配規則

如果依賴版本有差異但不影響功能，可以在「設定 → 預覽規則」中放寬匹配規則。

最佳實務

元件作者

• 在 README.md 中明確說明依賴要求
• 盡量使用相容性好的依賴版本
• 避免依賴特定次版本的功能

元件使用者

• 保持本機依賴版本相對較新，以提高元件相容性
• 對非關鍵依賴，可以使用「僅安裝」或「主版本」匹配
• 遇到問題時，優先檢查控制台錯誤訊息

常見問題

Q：為什麼元件提示「缺少依賴」但本機已安裝？

A：可能的原因：

1. 依賴名稱拼寫不一致（例如 echarts vs ECharts）
2. 依賴安裝在子目錄的 node_modules 中
3. 需要重新整理頁面重新偵測

Q：可以強制執行依賴不匹配的元件嗎？

A：您可以在「全部」列表中查看該元件，但能否正常執行取決於實際 API 差異。建議先解決依賴問題。

Q：匹配規則適用於下載的元件嗎？

A：匹配規則僅影響線上預覽。下載的元件在您的專案中使用您專案的依賴版本執行。