HomeAssistant本地开发环境搭建（Ubuntu）

发表于 2026-10-6 11:52:20

马上注册，结交更多好友，享用更多功能，让你轻松玩转社区。

您需要登录才可以下载或查看，没有账号？立即注册

×

Home Assistant 是本地智能家居中枢的主流选择，把各种品牌的设备收敛到一个平台里统一管理。想改它的源码、调试集成、提交补丁，就得搭一套开发环境，而不是装 Stable 版那么简单。官方开发者文档给出了环境要求，但实际操作里 Python 版本、系统依赖、源码目录这几处最容易卡住。本文在 Ubuntu 22.04 上走一遍完整流程：换源、编译 Python 3.12、拉代码、装依赖、启动实例。

一、先准备开发环境

建议用 Ubuntu 22.04.5 LTS，在 VMware 里跑一台虚拟机即可，同时装好 VS Code 便于在宿主机改代码、虚拟机里跑。开发流程对系统干净度敏感，虚拟机快照比反复重装省事得多。

二、把 apt 源换成国内镜像

默认源在国内下载慢，先备份再替换。

2.1 备份原源列表

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

2.2 编辑并替换

用 nano 打开 /etc/apt/sources.list（nano 里 Ctrl+K 是剪切整行、Ctrl+U 粘贴，比 vim 的 dd 好上手）：

sudo nano /etc/apt/sources.list

换成 Ubuntu 22.04（jammy）对应的阿里云镜像内容，注意 jammy、jammy-updates、jammy-backports、jammy-security 四组都要写全：

deb http://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse

2.3 更新索引

sudo apt update
sudo apt upgrade

这一步做完后 拍一个虚拟机快照——后面编译 Python 会装一大堆头文件，翻车时能一步回退。

三、从源码安装 Python 3.12

Ubuntu 22.04 仓库里的 Python 是 3.10，Home Assistant 开发要求 3.12 及以上，只能源码编译。

3.1 装编译依赖

把下面这条一次性装完，缺哪个头文件后面都会报杂七杂八的错：

sudo apt install -y software-properties-common build-essential libbz2-dev libssl-dev libreadline-dev libsqlite3-dev libncurses5-dev libgdbm-dev libnss3-dev libatk1.0-0 libx11-xcb1 libxkbcommon0 libxrender1 libxext6 libx11-6 libxfixes3 libxdamage1 libxcomposite1 libxcursor1 libxrandr2 libpangocairo-1.0-0 libpango-1.0-0 libgtk-3-0 libdbus-1-3 libexpat1 liblzma5 zlib1g libffi-dev libdb-dev libgdbm-dev liblzma-dev tk-dev uuid-dev libnsl-dev zlib1g-dev

3.2 下载并解压源码

到 Python 官网的 FTP 目录看有哪些版本可选，把下面命令里的版本号换成你要的（原文用的是 3.12.7）：

wget https://www.python.org/ftp/python/3.12.7/Python-3.12.7.tgz
tar -xf Python-3.12.7.tgz
cd Python-3.12.7

3.3 配置、编译、安装

建议一步一步执行，出错时能看到是在哪一步断的：

./configure
make -j $(nproc)
sudo make altinstall

这里用 altinstall 而不是 install，是为了不覆盖系统自带的 python3，避免把 apt 和桌面环境搞坏。装完验证：

python3.12 -V
pip3.12 -V

确认无误后再拍第二个快照。

3.4 软链接（按需）

想在终端里直接敲 python、pip 就用下面几条；不想动系统命令就跳过，后面带全版本号调用即可：

sudo ln -sf /usr/local/bin/python3.12 /usr/bin/python3
sudo ln -sf /usr/local/bin/python3.12 /usr/bin/python
sudo ln -sf /usr/local/bin/pip3.12 /usr/bin/pip3
sudo ln -sf /usr/local/bin/pip3.12 /usr/bin/pip

3.5 修一个常见小坑

做完软链接后发现快捷键唤不出终端，通常是 PyGObject 相关依赖缺失：

sudo apt-get install -y libcairo2-dev gir1.2-gobject-2.0 libgirepository1.0-dev
pip3 install PyGObject

再用 python3 -V 与 python -V 核对版本，按 Ctrl+Alt+T 确认终端能正常弹出，就可以进入下一阶段了。

四、拉取源码

打开 Home Assistant 的官方代码仓库页面，登录 GitHub 后点 Fork 到自己的账号下。
虚拟机里装 git，把 fork 下来的仓库克隆到本地：

sudo apt install git
git clone https://替换成你的用户名/你的仓库名

把源码再复制一份备份（cp -r 一份出来），或者干脆存到宿主机，避免恢复快照时把下载的内容一起丢了。
进入仓库目录，把官方仓库加为上游，方便同步上游改动：

cd 你的仓库目录
git remote add upstream https://官方仓库地址.git

五、装依赖并启动

5.1 一键装环境

script/setup

5.2 每次新开终端都要先激活虚拟环境

source venv/bin/activate

5.3 启动实例

hass -c config

浏览器打开 127.0.0.1:8123，界面会在中途就出现，但要等初始化跑完、出现完整前端才算启动完成。

六、踩坑与建议

顺序不要随意改：换源、装依赖、编译 Python 这三步之间有依赖，跳步会得到难以定位的错误。
快照要拍在关键点：换源后、编译 Python 后各拍一次，比事后排查省时间。
编译失败看 config.log：缺头文件通常在这一步暴露，装齐 -dev 包基本都能解决。
端口 8123 被占：用 lsof -i :8123 或 ss -tlnp 查是谁占的。
调试集成：调试阶段建议开 debug 日志级别，Home Assistant 的日志在配置目录下，排障时先看它。
别在生产机上这么干：源码环境已经是依赖最全的组合，日常使用仍建议装官方发布的稳定包。

整套流程最大的工作量其实在编译 Python 那一块，十几分钟的配置加编译，换来的是后续可以随意改代码、单测、提 PR 的自由度。按「换源 → 编译 → 快照 → 拉代码 → 装依赖 → 启动」这个顺序走稳，开发环境基本一次成型。

qidao123.com企服评测-应用市场编辑提示：本文为开发环境搭建的操作记录，已移除原文中的所有外链与图片；文中版本号仅为示例，请按当前官方要求选择可用版本，并在变更前确认虚拟机的快照可用。