1. 前言&&疊甲

本文章為全文皆慢慢敲的文字，本人非專業人士，難免存在遺漏和錯誤，請指出即可。若有更好方案，歡迎提出。

為什么會寫這篇文章？因為搜索了一段時候，發現很少有介紹從零開始編譯Home Assistant源碼的教程和視頻，大多是使用docker或者使用Nas，定制化/可修改程度不高？

同時由于官方的方案僅剩下為數不多的幾個，主要是基于HA OS（也就是做成了鏡像系統），或者是Container。一個是鏡像封裝了，不方便自定義和使用系統，另一個是不太利于沒有Docker環境。本篇想在裸機系統上部署，并且隨時能切換Git版本從而隨時升級，故寫此篇。

2. 使用的環境

操作系統版本：Ubuntu-Desktop 24.04.2 LTS。
Home Assistant版本：2025.7.1，但是是GitHub的最新dev構建。但是由于是源碼部署，所以可以隨時升級。
Python版本：3.13.5，源碼構建。否則可能會影響Ubuntu內置的3.12。2025.7版本的Home Assistant需要Python3.13。

3. 相關鏈接

本篇編寫時候的相關安裝包/軟件的鏈接如下，可以參考換成最新的

https://releases.ubuntu.com/24.04/ubuntu-24.04.2-desktop-amd64.iso
https://www.python.org/ftp/python/3.13.5/Python-3.13.5.tgz

相關GitHub倉庫鏈接如下

https://github.com/home-assistant/core
https://github.com/hacs/integration
https://github.com/XiaoMi/ha_xiaomi_home

4. 前期步驟

4.1 安裝路徑提前說明

為方便使用，本篇安裝都位于~/HomeAssistant-All/目錄下，包括Python、Home Assistant。

4.2 Ubuntu 相關依賴安裝

# 更新
sudo apt update# 安裝Home Assistant需要的依賴，和其他一些常用的工具。但不包括Nginx、Python等
sudo apt install -y autoconf automake avahi-daemon bluez build-essential ca-certificates curl ffmpeg gdebi git gnupg gnupg2 htop libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libbz2-dev libcap2-bin libffi-dev libgdbm-compat-dev libgdbm-dev libglib2.0-dev libjpeg-dev liblzma-dev libncursesw5-dev libnss3-dev libopenjp2-7-dev libpython3-dev libreadline-dev libsqlite3-dev libssl-dev libswscale-dev libtiff5-dev libtool libturbojpeg0-dev libudev-dev libxml2-dev libxmlsec1-dev libxslt1-dev libyaml-dev lrzsz lsb-release lsof neofetch net-tools openssh-server p7zip-full rar rsync software-properties-common tk-dev tmux tree unrar unzip uuid-dev vim wget xz-utils zip zlib1g-dev

以上依賴安裝較為緩慢。由于下載的Ubuntu鏡像默認使用的是清華的安裝源，所以在網絡上還是沒有問題的。若不是，請自行換源。出現如下表明安裝完成。

4.3 Python源碼編譯安裝

4.3.1 編譯安裝

為了防止干擾Ubuntu自帶的Python版本，此處Python僅在安裝文件夾中進行。若本機已經有Python3.13的環境，直接跳過至構建Home Assistant源碼即可。

將下載的Python源碼包Python-3.13.5.tgz解壓到~/HomeAssistant-All/，進入該目錄cd Python-3.13.5/。
然后開始編譯Python。

# 位于 ~/HomeAssistant-All/Python-3.13.5/
sudo ./configure --enable-optimizations
sudo make -j$(nproc)
sudo make altinstall

由于Python源碼編譯較慢，若機器配置較低可能需要數分鐘至十數分鐘。安裝完成后為如下。

安裝完畢后，可以執行

~/HomeAssistant-All/Python-3.13.5/python

看到如下則表明Python安裝成功，可以使用Ctrl+D退出。

4.3.2 換源

mkdir -p ~/.pip
vim ~/.pip/pip.conf

在里面輸入如下，即使用清華源。

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
timeout = 10
trusted-host = pypi.tuna.tsinghua.edu.cn

4.3.3 環境變量

此處環境變量不與系統的沖突，做到輸入命令python313方可運行。

vim ~/.bashrc

# 然后劃到最后，輸入
export PATH="$HOME/HomeAssistant-All/Python-3.13.5/bin:$PATH"
alias python313='python3.13'
alias pip313='pip3.13'

# 生效環境變量
source ~/.bashrc

新開終端，輸入python313即可正常使用Python3.13.5。

5. 構建Home Assistant源碼

5.1 clone源碼

將源碼clone到本地~/HomeAssistant-All/home-assistant-core/文件夾

git clone https://github.com/home-assistant/core.git home-assistant-core

進入該文件夾，cd home-assistant-core。

默認的clone下來的，可能是dev分支，dev分支push比較活躍，不清楚有沒有bug。可以使用如下命令查看和切換成穩定的master分支，或者是其他分支。

# 查看當前分支
git branch# 本地沒有master分支，從遠程拉取
git checkout -b master origin/master# 若本地有master分支，則切換到本地的master分支
git checkout master# 更新分支代碼
git pull

5.2 創建虛擬Python環境

直接覆蓋原本Python安裝的環境，可能會帶來依賴沖突。所以創建一個虛擬的Python環境，所有依賴都安裝到這個環境中，不會出現依賴問題。若因為某些原因環境出問題了，只需要刪除虛擬環境再建即可。

此處使用Python虛擬環境，名為venv313。

# 創建虛擬環境
python313 -m venv venv313
# 激活環境
source venv313/bin/activate

# 更新相關軟件包
pip install --upgrade pip setuptools wheel

5.3 安裝項目依賴

pip install -r requirements_all.txt

為什么使用requirements_all而不是requirements_test，是因為all能安裝所有依賴。test只有部分依賴，若運行中代碼走到沒有安裝的依賴，則會默認安裝，走的是pip的默認源，可能因為網絡問題無法下載，導致運行報錯。

安裝all的項目依賴會耗時較長時間，可能為十數分鐘。安裝完成后如下顯示

5.4 安裝項目

pip install -e .

5.5 運行項目

直接運行命令

hass

即可啟動項目。默認第一次運行，會在如圖的~/.homeassistant/文件夾下創建配置文件。出現下圖即說明已經成功在運行了。

使用http://ip:8123可直接訪問。

5.6 查看配置文件夾

cd ~/.homeassistant/

運行如上命令，即可進入Home Assistant的配置文件夾。可以修改端口號等信息，此處不再贅述。

5.7 補充相關

本篇全篇運行于基于VMware的Ubuntu中。若也有相同的，建議對VMware配置做網絡上的橋接，方便手機連接。

6. 訪問Home Assistant

瀏覽器訪問http://ip:8123即可訪問。

6.1 首次運行創建用戶

點擊創建我的智能家居，輸入用戶名和密碼即可創建。

輸入相關信息后，點擊創建賬戶，我這邊沒有任何反應，然后去看運行日志，發現有報錯。

KeyError: 'component.onboarding.area.living_room'

不知道是版本問題，還是什么問題。但是不影響使用。用戶已經創建，此處需要重啟應用。即使用Ctrl + C停止運行，再使用hass運行，再刷新網頁即可。

6.2 選擇家的位置

登錄后，出現要選擇家的位置。可以在輸入框中輸入中文的城市名稱。

這個地圖有時候需要特殊網絡才能搜索。但是不影響選擇。可以縮放地圖后，拖動地圖定位的標點，來選擇到自己所在的城市。

6.3 進入首頁

無腦下一步后，即可進入首頁，如圖

那么，至此為止，初級的Home Assistant部署運行完成。

下面將介紹如何添加HACS、如何添加小米的Ha Xiaomi Home（兩者可獨立安裝，也可以Ha Xiaomi Home通過HACS安裝）。

7. 安裝HACS

HACS官方的GitHub鏈接：https://github.com/hacs/integration/releases。

此處使用官方構建的HACS的release安裝到Home Assistant中。

7.1 下載HACS包

打開https://github.com/hacs/integration/releases，下載最新版的hacs.zip文件。

7.2 將hacs放置對應位置

進入到Home Assistant的配置文件夾~/.homeassistant/

cd ~/.homeassistant/

在該文件夾位置新建一個名為custom_components的文件夾。

進入該custom_components的文件夾，將hacs.zip文件解壓到這個文件夾中，保留最外層的文件夾，如圖。

7.3 添加HACS

完成后，重啟Home Assistant應用，進入路徑設置-設備與服務。

點擊右下角添加集成按鈕，搜索hacs，可以看到一個右側有橙色方塊的欄目（代表“自定義集成”），選擇后點擊提交。

7.4 HACS綁定GitHub

提交完成后，需要點擊轉圈的下方的鏈接，進行GitHub的授權。同時下方小字有8個字符的配對碼，需要復制粘貼至GitHub進行授權方可使用。


然后點擊Authorize hacs即可完成，如圖結果出現即可關閉該頁面。

完成后如圖所示界面，可以看到側邊有HACS的入口了。

點擊HACS，可以看到有較多可下載的擴展組件。

如果出現如圖的報錯，could_not_register則請排查，Home Assistant主機是否無法訪問GitHub。

至此，HACS集成進Home Assistant已完成。

8. 安裝小米的Ha Xiaomi Home

小米在2024年底開源了自家的Home Assistant的組件，GitHub鏈接：https://github.com/XiaoMi/ha_xiaomi_home。至此可以很方便地將米家生態接入到Home Assistant。

8.1 三種安裝方式

Ha Xiaomi Home官方介紹了3種接入方式，分別是源碼、HACS、單獨文件形式。此篇都將介紹。

這三種方法都是將Ha Xiaomi Home的代碼文件復制到指定位置（~/.homeassistant/custom_components/）后，重啟Home Assistant應用，從而可以在添加集成的地方搜索并添加小米的Home Assistant集成，并設置賬號信息。

所以三種方法均寫至復制完成，提示重啟為止。重啟之后的操作將在后面一小節的添加Ha Xiaomi Home到Home Assistant中有寫。

8.1.1 源碼構建形式

源碼形式的話，可以將源碼clone至本地任何位置，但請

不要同時：

1. 將源碼clone至~/.homeassistant/custom_components/
2. 將clone的文件夾命名為xiaomi_home

• 否則在構建的時候，將會出現覆蓋性問題。可以適當修改文件名。

此處將源碼clone至~/.homeassistant/xiaomi_home_git/，使用如下命令即可。

cd ~/.homeassistant/
clone https://github.com/XiaoMi/ha_xiaomi_home.git xiaomi_home_git

clone完畢后，進入目錄

cd xiaomi_home_git/

運行構建命令，將構建產物復制到~/.homeassistant/custom_components/。

# 給install.sh運行權限。當然也可以自行設置更小的權限。
chmod +x install.sh
# 將構建產物復制到~/.homeassistant/custom_components/。其中，custom_components路徑不要手動添加，因為在install.sh腳本中已經自帶該路徑，若添加了則會變成~/.homeassistant/custom_components/custom_components/xiaomi_home/從而無法識別。
./install.sh ~/.homeassistant/

運行后出現如下提示，即成功：Xiaomi Home installation is completed. Please restart Home Assistant.。根據提示重啟Home Assistant即可。

一至三的方法（選其一）添加完畢后，都需要重啟Home Assistant。重啟后，需要將Ha Xiaomi Home集成到Home Assistant并添加賬號。

后續更新Ha Xiaomi Home的方式，在Ha Xiaomi Home的Git目錄運行命令即可。

# 更新至最新的代碼
git pull
# 構建并復制最新產物
./install.sh ~/.homeassistant/
# 完成后重啟Home Assistant

8.1.2 單獨文件形式

打開https://github.com/XiaoMi/ha_xiaomi_home/releases鏈接，下載最新的xiaomi_home.zip的壓縮包。

進入到Home Assistant的配置文件夾~/.homeassistant/，在該文件夾位置新建一個名為custom_components的文件夾（如果已有，或者在上面HACS中有操作，則不必新建）。

進入該custom_components的文件夾，將hacs.zip文件解壓到這個文件夾中，保留最外層的文件夾，如圖。將壓縮包解壓到該文件。

至此，Ha Xiaomi Home已經添加到Home Assistant。現在需要重啟Home Assistant方可使用。下面介紹如何使用HACS來添加。

一至三的方法（選其一）添加完畢后，都需要重啟Home Assistant。重啟后，需要將Ha Xiaomi Home集成到Home Assistant并添加賬號。

8.1.3 使用HACS安裝Ha Xiaomi Home

點擊HACS欄目，搜索欄中輸入Ha Xiaomi Home，看到stars數較多的即是官方的集成。

點擊進入后，點擊右下角的download，將會自動下載到本地。但是該方法如果在網絡不佳的時候將會無法下載。此時建議使用上一種方式。

安裝完成后，點擊HACS選項卡，可以看到Xiaomi Home在列表中，并且是Pending restart，這時候重啟Home Assistant即可。

一至三的方法（選其一）添加完畢后，都需要重啟Home Assistant。重啟后，需要將Ha Xiaomi Home集成到Home Assistant并添加賬號。

8.2 重啟后添加Ha Xiaomi Home到Home Assistant

不論是直接文件復制形式，還是HACS添加，完成后需要集成進Home Assistant。重啟Home Assistant應用，進入路徑設置-設備與服務。

點擊右下角添加集成按鈕，使用英文搜索xiaomi，可以看到其中一個右側有橙色方塊的欄目（代表“自定義集成”），選擇該有橙色的欄目后點擊，按照說明一步步即可。

8.2.1 賬號授權認證和地址回調

一步步進行后，在拉起小米賬號登錄前，有一個步驟，這里需要點擊藍字的請點擊此處進行登錄才能拉起小米的賬號授權。


確認授權后，將會跳轉到一個新的頁面，網址的格式為：http://homeassistant.local:8123/api/webhook/1261686089886280620?code=xxxxxxxxxxxxxxxx。

顯然，這個網頁是無法訪問的。可以看到訪問的域名是homeassistant.local，這個域名是不存在的，ping該域名也沒有ip的解析。這個域名猜測是在做HAOS或者container的時候，寫入到系統的hosts指向的本地地址。

有兩種解決辦法，最簡單的就是，手動將訪問的域名前綴homeassistant.local:8123修改為目前訪問的ip:8123，然后回車訪問即可。或者可以在本機的hosts文件中，手動配置指向Home Assistant的ip的條目。

這里使用直接修改ip訪問。回車訪問后，這個頁面稍等幾秒即變成空白頁，或者被關閉。然后手動打開剛剛的授權頁面，稍等幾秒即可看到已經成功授權了。然后只要勾選要導入的設備即可。

需要等待一段時間添加完畢后即可使用。添加完成后，可以在概覽處看到原本在米家中的設備。

9. 總結

至此，在Ubuntu上從零開始編譯并運行Home Assistant源碼并集成HACS與小米開源的Ha Xiaomi Home的講述完畢。

本篇為了不使用官方的鏡像，不使用Container，直接裸Ubuntu系統部署并運行Home Assistant，為的是能夠有更好的安裝空間。現在太多教程在教如何使用各家Nas來安裝Home Assistant，對于沒有Nas的人比較不友好。使用Docker來安裝的則對沒有容器化部署的不友好。故寫本篇。