2、HACS安装实战：手动安装HACS（通过Samba或SSH）、HACS的前端配置与初始化

好，咱们直接进入正题。上一章聊了HACS是什么，这一章咱们动手装一遍。我见过不少新手在安装这一步卡住，其实说白了就两条路：要么用Samba拖文件，要么用SSH敲命令。你选哪个都行，我习惯两手准备——毕竟谁还没遇到过Samba突然连不上的情况呢？

2.1 准备工作：确认你的HA环境

动手之前，先确认三件事。我曾经帮一个朋友排查了半天，结果发现他装的是Home Assistant Core（纯Python环境），连config目录都找错位置——嗯，这种坑踩过一次就记住了。

检查项	要求	说明
HA版本	≥ 2024.1.0	太老的版本可能缺少HACS依赖的API
安装方式	HAOS / Supervised / Container	Core安装需要额外配置，不推荐新手尝试
网络环境	能访问GitHub	HACS本质是从GitHub拉取插件

2.2 方法一：通过Samba手动安装

Samba是最直观的方式——把HA的配置文件目录映射成你电脑上的一个网络磁盘，然后像操作本地文件一样操作它。

2.2.1 安装并启用Samba加载项

1. 进入HA的“设置 → 加载项 → 加载项商店”。
2. 搜索“Samba”并安装“Samba share”官方加载项。
3. 启动Samba，并设置一个你记得住的用户名和密码。
4. 在“配置”选项卡里，确认workgroup和你电脑的工作组一致（Windows默认是WORKGROUP）。

2.2.2 下载并放置HACS文件

1. 从HACS官方GitHub仓库（hacs/integration）下载最新版本的压缩包。
2. 解压后，你会看到一个名为custom_components的文件夹，里面有一个hacs子目录。
3. 在电脑的文件管理器里，访问\\你的HAIP地址\config（Windows）或通过“前往 → 连接服务器”输入smb://你的HAIP地址/config（macOS）。
4. 把解压出来的hacs文件夹整个复制到config/custom_components/目录下。

2.3 方法二：通过SSH手动安装

如果你习惯用命令行，SSH方式更干脆。我个人偏爱这种方式，因为敲几行命令比拖拽文件快得多，而且不容易出错。

2.3.1 安装SSH加载项并连接

1. 在加载项商店里搜索“SSH”并安装“SSH & Web Terminal”。
2. 启动后，在“配置”里设置一个密码或SSH密钥。
3. 用你喜欢的SSH客户端（比如Windows上的PuTTY，或者macOS/Linux自带的终端）连接：ssh root@你的HAIP地址 -p 22。

2.3.2 用命令行下载并解压HACS

连接成功后，依次执行以下命令：

# 进入HA配置目录
cd /config

# 如果custom_components目录不存在，就创建它
mkdir -p custom_components

# 进入目录
cd custom_components

# 下载最新版HACS（建议先到GitHub确认最新版本号）
wget https://github.com/hacs/integration/releases/latest/download/hacs.zip

# 解压
unzip hacs.zip

# 删除压缩包（可选，但建议删掉，保持目录整洁）
rm hacs.zip

2.4 重启HA并验证安装

无论你用哪种方法，文件放好后，都需要重启Home Assistant才能生效。

1. 在HA的“设置 → 系统 → 重启”里点击“重新启动”。
2. 等待HA完全启动（通常1-3分钟）。
3. 进入“设置 → 设备与服务 → 集成”，点击右下角的“添加集成”。
4. 在搜索框里输入“HACS”，如果看到了HACS的图标，说明安装成功了。

2.5 HACS前端配置与初始化

安装成功后，接下来就是初始化配置。这一步其实很简单，但有几个细节需要注意。

2.5.1 添加HACS集成

1. 在“添加集成”里选择HACS。
2. 系统会弹出一个确认框，告诉你HACS需要收集一些设备信息——说白了就是知道你的HA版本和已安装的集成列表，以便推荐兼容的插件。点击“同意”。
3. 接下来会要求你授权GitHub账号。HACS需要这个授权才能从GitHub仓库下载插件和卡片。

2.5.2 GitHub授权流程

这一步可能会让一些新手困惑，我拆开来讲：

1. 点击“授权”后，浏览器会跳转到GitHub的登录页面。
2. 登录你的GitHub账号（没有的话免费注册一个，不需要付费）。
3. GitHub会询问是否授权给“HACS”这个应用——说白了就是允许HACS读取公开仓库和创建Gist（用于存储配置）。点击“Authorize”。
4. 授权成功后，浏览器会显示一个设备码，把这个码复制下来，粘贴回HA的输入框里。

2.5.3 初始化完成后的界面

授权成功后，HA的侧边栏会出现一个“HACS”的入口。点击进去，你会看到三个主要标签页：

• 集成：管理自动化插件（比如小米、特斯拉的第三方集成）
• 前端：管理自定义卡片和面板（比如蘑菇卡片、布局卡片）
• 自动化：管理自动化蓝图（预置的自动化模板）

每个标签页里都有一个“探索并下载”按钮，这就是你以后淘插件的地方。

2.6 本章知识体系

下面这张图帮你理清手动安装HACS的完整流程：

2.7 常见问题与避坑

最后，分享几个我实际遇到过的问题，你遇到了可以直接对照排查。

问题	原因	解决方法
添加集成时搜不到HACS	文件路径不对或HA未重启	检查custom_components/hacs是否存在，重启HA
GitHub授权页面打不开	网络无法访问GitHub	配置HA的网络代理，或更换网络环境
授权成功后HA没反应	页面未自动刷新	手动刷新HA页面，或清除浏览器缓存
Samba连接不上	用户名密码错误或工作组不匹配	检查Samba配置，确认用户名密码正确