解决HACS更新Xiaomi Miot Auto主分支版本失败问题

在使用Home Assistant时，许多用户会通过HACS（Home Assistant Community Store）来安装和管理第三方集成。Xiaomi Miot Auto是一个广受欢迎的小米设备集成插件，但最近有用户反馈在HACS中尝试更新到主分支（master）版本时遇到了下载失败的问题。

问题现象

当用户在HACS界面中选择master分支并点击下载按钮时，界面会持续显示加载状态而无法完成更新。查看日志会发现以下关键错误信息：

Got status code 404 when trying to download https://github.com/al-one/hass-xiaomi-miot/releases/download/master/xiaomi_miot.zip

这表明HACS尝试从一个不存在的URL下载主分支版本的压缩包，导致404错误。

问题分析

经过深入分析，我们发现这实际上是HACS工作机制的一个变化导致的兼容性问题。HACS在下载不同版本时采用了不同的策略：

1. 对于正式发布版本（如v0.7.18），HACS会从GitHub releases下载预编译的zip包，路径格式为：/releases/download/版本号/插件名.zip

2. 对于主分支（master），HACS错误地尝试使用同样的下载路径格式，但实际上主分支代码通常不会被打包发布到releases中

正确的做法应该是直接从代码仓库下载源代码压缩包，路径格式应为：/archive/分支名.zip

解决方案

目前有两种可行的解决方法：

方法一：使用命令行安装

通过SSH连接到Home Assistant服务器，执行以下命令：

wget -O - https://get.hacs.vip | DOMAIN=xiaomi_miot ARCHIVE_TAG=master bash -

这个命令会使用正确的下载路径获取主分支代码并完成安装。

方法二：等待插件更新

插件开发者可以考虑以下两种修复方案：

1. 移除zip_release配置选项，让HACS默认从代码仓库下载

2. 设置hide_default_branch=true，避免用户误操作选择主分支

技术背景

这个问题反映了开源软件生态中版本管理的一个常见挑战。在GitHub工作流中：

• 主分支（master/main）代表最新的开发代码
• 发布版本（releases）是经过测试的稳定版本
• HACS作为中间层，需要正确处理这两种不同的代码获取方式

理解这种差异有助于用户在遇到类似问题时更快找到解决方案，也提醒插件开发者需要注意与HACS的兼容性配置。

总结

当遇到HACS更新主分支失败时，用户可以选择使用命令行工具临时解决，或者等待插件开发者调整配置。这个问题也提醒我们，在使用开源软件时，理解其底层工作机制能帮助我们更有效地解决问题。