HACS 社区商店完整使用手册

HACS 是什么

HACS（Home Assistant Community Store）是 Home Assistant 生态的社区应用商店。它让你不用再去 GitHub 上到处找社区开发的集成、卡片、App——HACS 把几千个社区项目整理好，点 Download 就能装。

HACS 是 Home Assistant 高级玩家必装的第一个东西。

HACS 能装什么

HACS 分五个类别：

类别	内容	举例
Integrations	自定义集成	小米 MIoT、Tesla、Daikin、Homekit Controller
Frontend	Lovelace 自定义卡片	Mushroom Cards、button-card、mini-graph-card、card-mod
Automations	Blueprint 合集	各类社区自动化蓝图
Themes	主题	Midnight、iOS-like、Slate、Nord
AppDaemon	AppDaemon 应用	进阶自动化框架的社区应用

Home Assistant OS 用户安装 HACS（推荐）

Home Assistant 2024.4 起，HACS 可以通过官方 App 仓库安装：

Settings → Apps → 右上角菜单 → Add repository
类型选 URL
填：https://github.com/hacs/addons
类别选 App
Add repository
搜索 HACS → Install
Start（只需要启动一次，后续自动运行）

启动后侧边栏会出现 HACS 图标 → 点进去按提示完成首次配置（需要 GitHub Token）。

Container 用户安装 HACS

Container 部署没有 App 商店，需要手动安装。参考 HACS 官方文档的 Container 安装路径，核心步骤：

安装 Home Assistant 社区 addons 仓库
在 Container 里运行 HACS 安装脚本
配置持久化目录映射

给 HACS 加 GitHub Token

HACS 会访问 GitHub API 来拉取项目信息。免费 API 有限流（60 次/小时）。Token 可以提升到 5000 次/小时：

访问 github.com/settings/tokens → Generate new token（classic）
Scope 勾选 public_repo 或完全留空（只读访问公开仓库）
生成后复制 Token
HACS → Settings → GitHub → Add token → 粘贴 → Save

使用 HACS 安装

浏览

HACS 首页会按类别展示 Featured 项目。想看全部：

Integrations 标签页 → 右下 Explore & download
可以按类别、关键词搜索、按 Star 数排序

安装

点击项目卡片 → 进入详情页（看功能介绍、截图、GitHub Star 数、最近更新时间）
点 Download → 确认 → 等待下载完成
某些集成需要 Home Assistant 重启或 App 重启

更新

HACS 有新版本更新时：

侧边栏 HACS 图标上会显示小红点（有更新数量）
HACS → Updates 标签页 → 点 Update 更新单个
或右上角菜单 → Update all 批量更新

卸载

HACS 找到已安装项目 → 点进去 → Remove
Home Assistant 重启
某些项目需要手动删除残留文件（重启后会提示）

HACS 管理的文件在哪里

HACS 下载的文件都在你的 Home Assistant config/ 目录下：

config/
├── custom_components/        # 自定义集成
│   ├── hacs/
│   ├── xiaomi_miot/
│   ├── tesla_custom/
│   └── ...
└── www/
    └── community/            # 自定义卡片
        ├── button-card/
        ├── mushroom-cards/
        └── ...

不要手动删除这些文件——让 HACS 管理。

安装的集成还要手动添加

HACS 下载集成文件 ≠ 自动启用集成。下载完后：

Home Assistant 重启（或集成要求的重启）
Settings → Devices & services → Add integration → 搜索刚装的集成名称
配置参数 → Save

安全注意

优先选 Stars 数高、最近有更新、Issues 数量少 的项目
不要一次装几十个自定义卡片和集成——每个都可能是故障源
HACS 会显示项目最后更新时间。长期（> 6 个月）不维护的集成可能有安全漏洞或不兼容新版本 Home Assistant
重要：保持 Home Assistant 和 HACS 都更新到最新稳定版——旧版本之间可能有兼容性问题

备份策略

HACS 管理的文件在 custom_components/ 和 www/community/ 目录下。整体备份 config/ 目录就包含了所有 HACS 内容。Home Assistant OS 的备份快照（Settings → System → Backups）也会自动包含。