把圖片放進 HA：/config/www 和 /local 到底是什麼關係

charles

這一步看起來很簡單，但是新手最常卡住的地方。

症狀通常是：圖片明明放進去了，但畫面上一片空白或顯示破圖。



一句話說明

你把檔案放在 `/config/www/`，在網頁上用 `/local/` 存取。

1. 檔案實際位置                          網頁上的網址
2. /config/www/home.png            →     /local/home.png
3. /config/www/floorplan/home.png  →     /local/floorplan/home.png
4. /config/www/icons/lamp.svg      →     /local/icons/lamp.svg

複製代碼

為什麼要換名字

因為 HA 只把 www 這個資料夾公開出去，
而公開出去之後它的對外名字就叫 local。

你不用懂為什麼，記住對應關係就好。

最常見的三個錯誤

1. ✗  /config/www/home.png      ← 這是檔案路徑，不是網址
2. ✗  www/home.png              ← 少了斜線開頭
3. ✗  /local/www/home.png       ← 多打了 www
5. ✓  /local/home.png

複製代碼

怎麼把檔案放進去

有四種方法，選你方便的。



方法一：File Editor 附加元件（最簡單）

• 設定 → 附加元件 → 附加元件商店
  
• 搜尋 File editor → 安裝 → 啟動
  
• 打開之後，左上角有一個資料夾圖示
  
• 找到 www 資料夾（沒有的話點「新增資料夾」建一個）
  
• 點上傳圖示，把你的圖選進去
  

沒有 www 資料夾是正常的 —— 新裝的 HA 不會自動建，要自己建一個。

方法二：Samba 分享（適合常常要換圖）

• 裝 Samba share 附加元件
  
• 設定帳號密碼、啟動
  
• 在 Windows 的檔案總管打 \\homeassistant\config
  
• 像操作一般資料夾一樣拖進去
  

這個最方便，尤其是你要反覆調整圖片的時候。

方法三：Studio Code Server（如果你已經裝了）

左邊的檔案樹直接拖拉上傳。

方法四：SSH / SCP（進階）

1. scp home.png root@你的HA:/config/www/floorplan/

複製代碼

建議的資料夾結構

不要把圖片全部丟在 www 根目錄，之後會很亂。

1. /config/www/
2. └── floorplan/
3.     ├── home.png              ← 底圖
4.     ├── home.svg              ← SVG 版本（之後會用到）
5.     ├── rooms/
6.     │   ├── living_on.png     ← 客廳亮燈的圖層
7.     │   ├── kitchen_on.png
8.     │   └── bedroom_on.png
9.     └── transparent.png       ← 一張全透明的圖（很重要，等等說明）

複製代碼

放完一定要先驗證（不要跳過這步）

不要直接去做卡片。先確認圖片真的讀得到。

方法：直接在瀏覽器打開那個網址

1. http://你的HA位址:8123/local/floorplan/home.png

複製代碼

• 看到圖片 → 成功，可以進下一步
  
• 404 Not Found → 路徑錯了或檔案沒上傳成功
  
• 一片空白 → 檔案是空的，或格式不對
  

這一步花十秒，可以省下之後半小時的「為什麼卡片是空的」。

一個很容易忽略的坑：快取

換了圖片但畫面沒變？

瀏覽器會把圖片快取起來，你換了檔案它還是顯示舊的。

三個解法：

• 強制重新整理：Ctrl + F5（Windows）或 Cmd + Shift + R（Mac）
  
• 換檔名：home2.png、home3.png……（最可靠，但要改卡片設定）
  
• 在網址後面加參數：/local/floorplan/home.png?v=2
  

第三個最實用 —— 檔名不用改，只要把 v 的數字加一就好。

那張「全透明的圖」是什麼

之後做「燈亮才顯示」的效果時會用到。

原理：image 元素可以依照實體狀態換圖片。

1. light.living_room 是 on   →  顯示 living_on.png（亮燈效果）
2. light.living_room 是 off  →  顯示 transparent.png（什麼都沒有）

複製代碼

所以你需要一張「什麼都沒有」的圖。

怎麼做一張全透明的 PNG：

• 用小畫家 3D、GIMP、或線上工具建一張 1×1 的透明 PNG
  
• 或者 Google 搜尋「transparent png 1x1」下載一張
  
• 或者用 Inkscape 建一個空白畫布另存成 PNG
  

大小完全不重要（1×1 就好），因為它本來就是隱形的。

一個進階但很有用的設定：allowlist_external_dirs

如果你之後想從別的地方讀圖片（例如 /media），
要先在設定裡允許：

1. # configuration.yaml
2. homeassistant:
3.   allowlist_external_dirs:
4.     - /media
5.     - /config/www

複製代碼

一般做平面圖用不到，但如果你要做「攝影機快照放在平面圖上」，
就會需要。

檢查清單

做下一篇之前，確認：

• 圖片在 /config/www/floorplan/ 底下
  
• 在瀏覽器打 /local/floorplan/你的檔名.png 看得到圖
  
• 有一張全透明的 PNG 備用
  
• 圖片寬度在 1000-2000 px 之間、檔案小於 500KB
  

---

下一篇：做出你的第一張可以點的平面圖。

這一篇做完你就會看到成果了。