【card-mod 實作】從裝 HACS 開始，一步步做到「卡片依狀態變色」

charles · 發表於 2026-9-21 13:00:06

這篇的內容（9 段）

做完這篇你會有什麼
為什麼 card-mod 這麼多人卡住
第二步：裝 HACS
情況 B：Docker Container
情況 C：Core / venv 安裝
第三步：用 HACS 下載 card-mod
變體：裝置離線時變半透明
除錯對照表（照順序查）
最後一個提醒

這篇從「HACS 都還沒裝」開始，做到一張會依狀態變色、圖示會放大、字級自己調過的卡片。

每一步都有「你會看到什麼」。做完第三步能自己確認第三步成功了，才走第四步。

做完這篇你會有什麼

HACS 裝好並完成 GitHub 授權
card-mod 裝好，而且你有一個十秒就能重測的方法確認它到底有沒有載入
四張可以直接複製貼上的完整卡片設定：改外觀、依狀態變色、改圖示、改文字
會用瀏覽器開發者工具自己找出「要改的那個元素叫什麼」——這是 card-mod 最大的門檻

為什麼 card-mod 這麼多人卡住

因為它失效的時候是完全安靜的。

沒有紅字、沒有錯誤通知、YAML 也存得進去，畫面就是一點變化都沒有。這時候你分不出是三件事裡的哪一件：card-mod 根本沒載入、你的 CSS 選擇器選錯了、還是你的樣式被別的樣式蓋過去。

所以這篇把「確認它載入了」獨立成一步，而且給你一個不會有第二種解釋的測試方法。

---

第一步：先查你的 Home Assistant 版本

這一步不能跳過，因為 card-mod 要裝哪一個版本完全由 HA 版本決定。

做法：在 HA 的網址列直接輸入 /config/info（例如 `http://homeassistant.local:8123/config/info`），或走選單「設定 → 系統 → 修復 → 右上角三個點 → 系統資訊」。

你會看到什麼：一個「關於」頁面，最上面那行寫著 Home Assistant Core 的版本，格式像 2026.9.3。把這個數字記下來。

照這個數字對表：

2026.2.0 以下 —— card-mod 4.x 不支援，請先把 HA 升上去，不要硬裝舊版 card-mod
2026.2 到 2026.7 —— 裝上游版本（就是 HACS 裡搜尋 card-mod 出來的那個），目前是 4.2.1
2026.8 以上（包含現在的 2026.9.x） —— 一樣先裝上游，但要知道有一個已知問題，第五步會教你怎麼判斷自己有沒有中

2026.8 的已知問題是什麼：上游 card-mod 用來處理「主題層設定」的那段載入程式，會去等一個叫 `developer-tools-router` 的前端元素，而那個元素從 HA 2026.8 起已經不存在了。結果是：只要你的佈景主題裡有任何 `card-mod-*-yaml` 開頭的設定，整個頁面的 card-mod 樣式全部不會套用。

如果你沒有在主題裡寫 card-mod 設定（大多數人都沒有），上游版本照樣能用。所以正確順序是先裝上游、用第五步的測試卡驗一次，真的不行再換維護分支（第九步）。

---

第二步：裝 HACS

card-mod 不是內建的，要透過 HACS（Home Assistant Community Store）下載。裝 HACS 的方法近兩年換過，網路上很多教學還停在舊方法。

先確認你是哪一種安裝方式（同樣在 `/config/info` 那頁看得到）：

情況 A：Home Assistant OS 或 Supervised（大多數人是這個）

官方現在建議用附加元件裝，不需要 SSH，也不用打指令：

「設定 → 附加元件 → 右下角附加元件商店」
右上角三個點 → 存放庫
貼上 https://github.com/hacs/addons → 新增 → 關閉
回到商店，往下捲找到 Get HACS → 點進去 → 安裝
安裝完按啟動，然後切到那個附加元件的日誌分頁

你會看到什麼：日誌裡會印出一段文字，告訴你檔案已經放好了，並要你重新啟動 Home Assistant。照著做：「設定 → 系統 → 右上角重新啟動 → 重新啟動 Home Assistant」。

情況 B：Docker Container

在主機上打：

docker exec -it homeassistant bash
wget -O - https://get.hacs.xyz | bash -
exit
docker restart homeassistant

複製代碼

（`homeassistant` 要換成你自己容器的名字，用 `docker ps` 查。）

情況 C：Core / venv 安裝

切到跑 HA 的那個使用者，在設定目錄底下執行：

wget -O - https://get.hacs.xyz | bash -

複製代碼

然後重新啟動 HA。

三種情況共通的收尾（很多人漏掉這段，以為裝完就好了）

重啟完，在瀏覽器按 Ctrl+Shift+R（Mac 是 Cmd+Shift+R）做一次硬重新整理
「設定 → 裝置與服務 → 右下角新增整合」→ 搜尋 HACS
把三個確認方塊全部勾起來 → 送出
畫面會給你一串代碼和一個 github.com/login/device 的連結，開那個連結、貼上代碼、按授權

以下還有約 80% 的內容
登入後即可閱讀完整教學

登入繼續閱讀使用 Google 登入

		自動登入	找回密碼
密碼			立即註冊

【card-mod 實作】從裝 HACS 開始，一步步做到「卡片依狀態變色」

延伸閱讀

瀏覽過的版塊