主題與外觀個人化

為什麼要學這個

前面 12 章你已經把功能做完了：裝置有名字、區域有樓層、儀表板有分頁、自動化會自己跑。可是打開手機那一秒，看到的還是那個一開始就長那樣的畫面。

這件事比你想的重要。介面醜，你就不想開；不想開，你就會退回去用實體開關，然後整套系統慢慢變成「當初裝好玩的」。相反地，只要顏色跟你家的燈光、你的手機桌布、你半夜起床的眼睛對得上，你就會一直用它。

這章會處理三種很具體的痛：

• 晚上刺眼：白底介面在半夜滑手機等於閃光彈。你要的是跟著系統自動切深色。
• 一家人口味不同：你喜歡黑底霓虹，媽媽覺得看不到字。好消息是主題可以「每個使用者各自一套」。
• 看起來像半成品：預設藍配色 + 瀏覽器分頁寫著「Home Assistant」，放在牆上平板就是很像工程師的測試機。

會用到 HACS 的部分，如果你還沒裝過，先回附錄 A把 HACS 裝起來再回來。儀表板本身的編輯方式在第 6 章講過了，這裡不重複。

主題（Theme）到底是什麼東西

很多人以為主題是「一張皮」，換上去整個介面就重畫。不是。Home Assistant 的主題其實只是一疊顏色設定值，官方叫它 CSS 變數（CSS variables）。

想像你家牆上有一排標籤紙：

• 一張寫「主色 = 天空藍」
• 一張寫「卡片底色 = 白」
• 一張寫「主要文字 = 深灰」

介面上每一個元件都不是自己決定顏色，而是跑去看標籤紙。所以你只要把標籤紙上的字擦掉重寫，全站的按鈕、卡片、側邊欄就會一起變。這就是為什麼一份幾十行的主題檔可以改掉整個系統的外觀。

也因為是這種機制，主題有它的天花板：

另外要先分清楚三個常常被講混的東西：

換主題不會動到你的卡片，換卡片也不會動到主題。兩件事是分開的。

主題設定住在哪裡（近期改過位置，請注意）

這是最容易踩空的一段，因為 Home Assistant 在 2026.2 版動過刀。

現在的位置：個人資料頁。點側邊欄最下方你自己的名字，個人資料頁分成「一般（General）」和「安全性（Security）」兩個分頁，主題選擇器在一般分頁的「使用者偏好（User preferences）」區塊裡，官方對它的一句話說明就是「Home Assistant 看起來長什麼樣」。

2026.2 的官方改版說明寫得很直白：「主題搬家了！你現在可以直接在你的使用者個人資料裡找到並切換你喜歡的外觀，讓你在任何登入的裝置上都能套用同一套主題。」

個人資料頁的主題區塊通常有兩層選擇：

1. 選一個主題

   下拉選單裡至少會有「預設（Default）」，再加上你之後安裝的所有社群主題。剛裝好的系統只會有預設那一個，這是正常的。

2. 選明暗模式

   同一個主題如果同時提供了 light 與 dark 兩種模式，你就能再選要亮的還是暗的。沒特別指定的話，它會跟著你手機或電腦本身的深色模式走——手機轉深色，Home Assistant 也跟著轉。想固定成一種就自己指定，想省事就別動它。

   這個選項在不同版本上的名字和位置不太一樣（有的版本是「自動」，有的是一組亮／暗按鈕），以你自己畫面上看到的為準，認「跟著系統」這個行為就好。

順帶一提，同一次改版也把「開發者工具」從側邊欄搬進了設定底下，官方說法是「工具已移至設定區域」。到了 2026.8 又進一步把名稱從「Developer tools」簡化成「Tools（工具）」。所以本章之後講到的路徑會寫成設定 → 工具；如果你的版本比較舊，那就是側邊欄的「開發者工具」，內容一樣。

先選路線：戰情室，還是留白？

動手之前先決定風格，不然你會裝了十個主題然後每天換一個，最後一團亂。實務上大部分人的品味會落在兩條路線的其中一條。

一個很好用的分法：「監控用的畫面」走戰情室，「操作用的畫面」走留白。你自己看的能源統計頁面資訊塞爆沒關係；玄關那台給全家人按的平板，就該是三顆大按鈕加一片白。

好消息是這兩條路線可以並存——後面「單一分頁換主題」那一節就是幹這個用的。

內建主題 vs. HACS 社群主題

Home Assistant 本身出廠只給你一套「預設（Default）」主題，它自帶淺色與深色兩個模式。2026.2 版把這套預設主題整個重畫過，官方的說法是「我們捨棄了舊的藍色頂列，換成跟設定頁一致的乾淨風格」。所以如果你是從很舊的版本升上來，會覺得整個系統忽然變素了，那不是壞掉。

想要更多選擇，就有三條路：

挑社群主題的時候，用第 11 章挑整合的同一套標準：先看最後更新日期。一個兩年沒動過的主題，很可能還在用早就被拿掉的變數名稱，裝上去會有一半地方沒生效。

動手做：從零裝好第一個社群主題

整條流程有五步。第 2、3 步是新手最容易漏掉的，漏了就會出現「HACS 說裝好了，但個人資料頁裡什麼都沒多出來」這個經典卡關。

1. 在 HACS 裡下載主題

   打開 HACS，用搜尋框找你要的主題名稱，進去按下載。HACS 官方文件寫得很清楚：「任何透過 HACS 下載的主題，都會存放在你的 Home Assistant 設定資料夾底下的 themes/ 資料夾裡。」也就是一般人講的 /config/themes/。

   HACS 的分類名稱是「Theme（主題）」。如果你的 HACS 沒看到主題分類，通常是因為系統還沒啟用主題功能，做完下一步就會出現。

   

2. 在 configuration.yaml 加三行

   用「檔案編輯器（File editor）」或「Studio Code Server」這類 add-on 打開設定資料夾裡的 configuration.yaml，在最外層加上：

   frontend:
     themes: !include_dir_merge_named themes

   這三行的意思是「把 themes/ 資料夾裡的所有檔案，合併成主題清單」。!include_dir_merge_named 是 Home Assistant 自己的語法，不是一般 YAML，照抄就好。官方 frontend 文件裡也示範過用自訂資料夾名稱的寫法，例如 !include_dir_merge_named my_themes，但配合 HACS 就固定用 themes 最省事。

   如果你的 configuration.yaml 裡已經有 frontend: 這一行了，不要再加第二個，直接把 themes: 那行接在它底下。YAML 不允許同一層出現兩個一樣的鍵。

3. 檢查設定有沒有寫錯

   到設定 → 工具 → YAML，先按檢查設定的按鈕。官方文件說這個分頁「提供按鈕來觸發設定檔檢查，以及重新載入設定」。有紅字就照著訊息改，通常不是縮排錯就是多打了一個冒號。

   危險：設定檔有語法錯誤時直接重啟，Home Assistant 會起不來，你會看到一片空白或連不上。務必先檢查再重啟，這是唯一能救你的步驟。真的重啟掛掉了，就照第 9 章還原備份。

4. 重新載入主題

   第一次新增 frontend: 這個區塊時，請完整重啟一次 Home Assistant。之後如果只是改主題內容或新裝一個主題，就不用重啟了——到設定 → 工具 → 動作（Actions），執行 frontend.reload_themes 這個動作。它沒有任何參數，YAML 模式下就這麼一行：

   action: frontend.reload_themes

   官方對它的描述是「從你的 configuration.yaml 重新載入主題設定」，不需要重啟。文件另外提醒：如果你目前用的主題在重新載入後不存在了，系統會退回標準主題。這個動作只有管理員能執行。

   設定 → 工具 → YAML 這個分頁本身也能重新載入設定，官方的說法是：「快速重新載入（Quick reload）會重載全部設定，而 YAML 分頁讓你一次只重載某一項設定。」你的版本上如果那份清單裡剛好有主題，按它跟執行上面的動作是同一件事；沒有的話就用動作，不用糾結。

   

5. 回個人資料頁套用

   點側邊欄最下方你的名字，在一般分頁找到主題選擇器，下拉就會看到剛裝的主題。選下去，畫面應該立刻變色——不需要重新整理，不需要重登。

   沒立刻變的話，先做一次強制重新整理（Ctrl + Shift + R），瀏覽器快取是最常見的兇手。

自己寫一份主題：YAML 結構與變數速查

看懂了別人的主題檔，你就有辦法微調它，也有辦法從零寫一份。官方 frontend 文件給的最小範例長這樣：

frontend:
  themes:
    happy:
      primary-color: pink
      accent-color: orange
    sad:
      primary-color: steelblue
      accent-color: darkred

如果你是用前面的 !include_dir_merge_named themes 寫法，那就在 /config/themes/ 底下開一個新檔，例如 my_home.yaml，檔案裡不要再寫 frontend: 和 themes:，直接從主題名稱開始：

my_home:
  primary-color: "#2f8f6b"
  accent-color: "#e0a458"
  primary-text-color: "#1c1c1c"
  card-background-color: "#ffffff"
  primary-background-color: "#f4f2ed"

顏色可以寫英文名（pink）、16 進位（"#2f8f6b"）或 rgb(47,143,107)。用 # 開頭時記得加引號，不然 YAML 會把它當成註解，這是新手第一名的錯誤。

深色與淺色兩種模式

真正好用的主題會同時提供兩種模式。官方的寫法是加一個 modes: 區塊：

day_and_night:
  primary-color: coral
  modes:
    light:
      secondary-text-color: olive
    dark:
      secondary-text-color: slategray

套用順序官方講得很細，值得記起來，因為它解釋了「為什麼我改了沒用」：

1. 先鋪預設主題

   系統先把預設主題的所有變數當底。所以你沒寫到的變數，不會變成透明或黑掉，而是沿用預設值。

2. 再蓋上不分模式的設定

   也就是寫在 modes: 外面、頂層的那些變數。上例中的 primary-color: coral 不管亮暗都會生效。

3. 最後蓋上該模式專屬的設定

   寫在 modes: light: 或 modes: dark: 底下的，優先權最高。同一個變數在頂層和模式裡都寫了，模式裡的贏。

文件另外交代兩個行為：舊格式（完全沒有 modes: 的單一主題）會自動以預設淺色主題為底；如果一份主題只定義了 dark，那這個模式就會被自動採用。

常用變數速查

變數名稱在 YAML 裡寫的時候不加前面的兩條槓，但在 card-mod 或 CSS 裡引用時要寫成 var(--primary-color)。下面挑最有感的：

「開著的燈是什麼顏色」比你想的複雜

圖示顏色是最多人卡住的一塊，因為它不是一個變數說了算。官方 frontend 文件寫明，系統會照下面這個順序去找，寫得越指名道姓的越優先，找到第一個就用它、後面的不看：

實際情境：你想讓客廳的燈開著時是暖橘色、但冷氣開著時是藍色，就不要動最通用的那一層，改寫 state-light-active-color 和 state-climate-active-color，兩者互不干擾。反過來，想一次把「所有開著的東西」都換色，才動 state-active-color。

讓不同分頁長不一樣，以及自動換主題

單一 View 指定主題

這就是前面說的「戰情室與留白並存」怎麼做。儀表板的每一個檢視（View）都可以自己指定主題，官方 View 文件裡列的設定變數就寫著「theme：字串（選填），為此檢視與其中的卡片套用主題」。

做法很簡單：進儀表板編輯模式，點你要改的那個分頁的鉛筆圖示，在設定裡找到主題欄位選一個。想直接寫 YAML 的話，官方範例是：

- title: Home
  theme: happy

放到實際情境：主儀表板留給全家人，用簡約留白；另外開一個「系統」分頁，指定成深色高密度主題，專門放 CPU、網路、電池、Zigbee 訊號那些只有你會看的東西。兩者互不干擾。

用自動化換全站預設主題

系統層級的預設主題可以用動作換掉，官方文件的用途說明是「為所有人設定預設的淺色與深色主題，例如白天用亮一點的、晚上自動換成暗一點的」。動作叫 frontend.set_theme，官方範例是：

action: frontend.set_theme
data:
  name: "HA Light"
  name_dark: "HA Dark"

兩個參數的官方定義：name 是淺色模式要用的主題，填 "default" 代表回到標準主題；name_dark 是深色模式要用的主題，填 "none" 代表移除覆寫。兩個至少要填一個。設定會被儲存，重啟後還在，而且只有管理員能執行。

接上第 8 章學過的三段式，日落換主題就是這樣：

alias: 日落換成深色主題
triggers:
  - trigger: sun
    event: sunset
actions:
  - action: frontend.set_theme
    data:
      name: "my_home_dark"

card-mod：主題改不到的地方

主題只能改「官方留了標籤紙的地方」。當你想做的是「把這張特定卡片的標題字放大」「這顆按鈕的圖示轉 45 度」「溫度超過 28 度時整張卡片變紅」，那已經超出主題的範圍了，要用 card-mod。

card-mod 是 HACS 上的前端自訂元件，作用是「把 CSS 樣式塞進任何一張儀表板卡片」。它目前仍在維護，作者在專案頁放了一張版本對照表——裝錯版本是最常見的「照著教學做卻沒反應」原因，先對一下你的 HA 版本：

HACS 預設會裝最新版，所以如果你的 HA 沒跟上最新版，記得在 HACS 的下載視窗裡手動選版本，不要直接按下去。

用法是在卡片設定的 YAML 最底下加一段 card_mod:：

type: entity
entity: sensor.living_room_temperature
card_mod:
  style: |
    ha-card {
      color: red;
    }

ha-card 是卡片最外層的元素，大括號裡就是標準 CSS。要沿用主題的顏色而不是寫死，就引用變數：

card_mod:
  style: |
    ha-card {
      border: 1px solid var(--primary-color);
      border-radius: 18px;
    }

Rebrand：換掉「Home Assistant」這幾個字

牆上平板、或者辦公室要給同事用的時候，很多人會想把瀏覽器分頁標題、圖示、加到主畫面之後的名字，換成自己家或公司的。先說結論，這一段要誠實講清楚：

目前實務上的幾條路：

關於 extra_module_url，這是官方 frontend 整合有記載的功能，寫法是：

frontend:
  extra_module_url:
    - /local/my_module.js

/local/ 對應的是設定資料夾底下的 www/ 資料夾。官方說明模組會用 import() 的方式載入。這是「合法的門」，但門後面要放什麼得你自己負責。

至於 PWA（把 Home Assistant 加到主畫面後變成的那個「假 App」）的名稱，它來自伺服器送出的 manifest 檔，官方沒有開放設定。最務實的做法還是第一列那個：在手機上按「加到主畫面」的當下，系統會讓你編輯名稱，改那裡就好，零風險。

介面語系、字型與中文顯示

切換介面語言

語言有兩個層級，很多人搞混：

個人資料頁的在地化設定除了語言，還一起管時區、數字格式、時間格式、日期格式、一週的第一天。官方文件對這一整區的說法是「使用者偏好與你的帳號綁定，會跟著你到每一台你登入的裝置」。所以住在同一個家、但習慣 12 小時制的家人，可以自己設自己的，不會互相影響。系統層級的地區設定（時區、單位、貨幣、國家、語言）在第 2 章設過了，這裡不重複。

Home Assistant 的翻譯是社群透過 Lokalise 這個平台做的，每次發版都會把最新翻譯打包進去。繁體中文長期都在支援清單裡，選單上會直接顯示中文名稱；但因為是志工翻譯，新功能剛推出的頭幾個月常常還是英文，這很正常，等下一兩版通常就補上了。

中文字型與排版的實際問題

Home Assistant 沒有內建中文字型，它是直接叫瀏覽器用系統字型。所以同一個畫面在不同裝置上會長得不一樣：

• iPhone / iPad / Mac：通常是蘋方，中文顯示最好看，幾乎不用調。
• Android：思源黑體系列，也不錯。
• Windows：常常掉到微軟正黑體，字重偏細，深色底上會顯得糊。
• 便宜的中國牌平板：最容易出事，可能整套只有簡體字型，繁體字會缺字或變成方框。

三個很實用的對策：

1. 名稱不要取太長

   中文字比英文寬很多。「客廳沙發後方立燈」在手機卡片上一定會被截斷成「客廳沙發後方...」。四到六個字最保險。第 4 章的命名原則在這裡會直接反映在畫面上。

2. 字重比字型重要

   深色底 + 細字＝糊。如果你的主題是深色的，讓文字顏色亮一點會比換字型有效得多，因為換字型要靠第三方模組，換顏色改一個變數就好。

3. 牆上平板先實測

   不要在電腦上調完就以為結束。走到那台平板前面，站在你平常會站的距離看一次。字太小、按鈕太小這種事，只有站在現場才會發現。

深色模式的對比與無障礙

做深色主題最常見的失敗，不是不好看，是看不見。而且做的人往往看得見——因為你在明亮房間、用高階螢幕、眼睛還年輕。你阿嬤在客廳看不見。

幾條可以直接照做的規則：

另外提醒兩個實體環境因素，這是螢幕前面調不出來的：

• 陽台和門口的手機：大太陽底下，淺色主題其實比深色主題好讀。如果你常在戶外用，別把模式鎖死在深色，交給「自動」比較聰明。
• 半夜起床：這時候你要的不只是深色，是「低亮度」。手機系統的深色模式加上自動亮度已經處理了大半，主題只要別用大面積白色卡片就好。

常見卡關

1. HACS 說裝好了，但個人資料頁的下拉選單裡沒有

   九成是 configuration.yaml 沒加 frontend: themes: !include_dir_merge_named themes，或加了但還沒重啟過。第一次新增 frontend: 區塊一定要完整重啟一次，之後才能只用 frontend.reload_themes。

   剩下一成是資料夾名稱對不上：你寫 themes，但 HACS 存在別的地方，或你手動建的資料夾多了一層。去設定資料夾確認 themes/ 底下真的有 .yaml 檔。

2. 設定檔檢查噴 YAML 錯誤

   按出現順序檢查這四樣：縮排有沒有用到 Tab（YAML 只吃空白）、冒號後面有沒有空一格、# 開頭的顏色有沒有加引號、是不是不小心有兩個 frontend:。第四個最陰險，因為錯誤訊息常常指到別的行號。

3. 主題選了沒反應，或整個畫面變黑

   先強制重新整理（Ctrl + Shift + R），再試無痕視窗。都不行的話，把主題切回「預設」確認系統本身是好的——如果切回預設就正常，那是那份主題檔跟你的版本不相容。

   另外，前端偶爾會出現主題套用失效的回報，通常在後續小版本修掉。如果是升級後才發生的，先去看你這版的更新說明和已知問題，不要急著重寫主題檔。

4. 我改了變數，但畫面某個地方就是不變

   三個可能：那個元件根本沒吃你改的變數（用瀏覽器檢查工具點它，看它實際用哪個）；你的變數寫在 modes: 頂層但被模式裡同名的值蓋掉了；那個變數在新版已經改名或移除。官方變數清單自己標著施工中，不完整是常態。

5. 手機是深色、電腦是淺色，我想要兩台不一樣

   2026.2 之後主題綁在帳號上，同帳號所有裝置一致，官方目前沒有打算改回可以分裝置。唯一的辦法是幫那台裝置開一個獨立使用者登入。這確實麻煩，但目前就是這樣。

6. 寫了 frontend.set_theme 自動化，自己看不到效果

   因為使用者自己在個人資料頁選的主題，優先權高於系統預設。把個人資料頁的主題選回「預設」，自動化才會影響到你。

7. card-mod 樣式升級後全跑掉

   先確認 card-mod 版本和你的 HA 版本對得上（作者專案頁有對照表），需要的話在 HACS 裡更新。如果版本對但樣式還是錯位，就是官方元件的內部結構改了，只能重新調整選擇器。這是用 card-mod 的固定成本。

8. 找不到「開發者工具」了

   2026.2 把它從側邊欄移進了設定底下，2026.8 又把名字簡化成「工具」。現在的位置是設定 → 工具，YAML、狀態、動作、範本這些分頁都還在裡面，功能沒少。

常見問題