Home Assistant 2025.12.2 +版本的 Sonos 产品添加详细教程。内容已经过最新版本逻辑验证，即便是小白用户也能顺利完成配置。
🟢 准备工作 (必读)
在开始之前，请确保满足以下 3 个核心条件，否则 Home Assistant (HA) 可能无法找到你的 Sonos 音响：
- 同一局域网： 你的 Home Assistant 主机（如树莓派、软路由等）必须和 Sonos 音响连接在同一个路由器/同一个网段下。
- 注意：如果你的 HA 运行在 Docker 或虚拟机中，请确保网络模式为
Sonos 设备已联网： 确保你的 Sonos 音响已经在官方 App 中配置完毕，且能正常播放音乐。
开启 UPnP (关键步骤)：
- 打开手机上的 Sonos App。
- 进入 设置 (Settings) ->管理 (Manage) ->系统设置 (System Settings)（不同版本 App 路径可能微调，但在账户/隐私或网络设置中）。
- 找到并开启 UPnP 选项。这允许 HA 自动发现音响。
🚀 教程：在 Home Assistant 中添加 Sonos
方法一：自动发现（最简单，推荐）
Home Assistant 2025.12 版本对自动发现功能优化很好，通常你只需登录后台即可看到提示。
- 登录 HA 后台。
- 查看左侧菜单栏的 配置 (Settings)，如果出现蓝色角标，说明发现了新设备。
- 点击 配置 (Settings) ->设备与服务 (Devices & Services)。
- 在顶部你会看到 “已发现 (Discovered)” 区域，应该会显示 Sonos。
- 点击蓝色的 配置 (Configure) 按钮。
- 点击 提交 (Submit)。
- 系统会自动配置所有音响，完成后会提示你将它们分配到具体房间（如客厅、卧室）。分配完成后点击 完成 (Finish)。
方法二：手动添加（如果没自动弹出）
如果“已发现”里没有 Sonos，请按以下步骤手动添加：
- 在 HA 左侧菜单点击 配置 (Settings)。
- 选择 设备与服务 (Devices & Services)。
- 点击右下角的蓝色按钮 + 添加集成 (+ ADD INTEGRATION)。
- 在搜索框输入 Sonos。
- 点击搜索结果中的 Sonos 图标。
- 系统会尝试自动搜索局域网内的设备：
- 情况 A： 搜索到了，点击提交即可（参考方法一步骤）。
- 情况 B： 如果提示输入 Host (主机/IP)，你需要填写其中任意一个 Sonos 音响的 IP 地址。
- 如何查看 IP？ 在路由器后台或 Sonos App 的“关于我的系统”中可以找到（例如 192.168.1.100）。
输入 IP 后点击 提交，HA 会通过这台设备顺藤摸瓜找到所有其他 Sonos 设备。
✅ 验证与使用
添加成功后，我们需要验证设备是否可用，并添加到仪表盘。
- 确认设备状态：
- 回到 配置 ->设备与服务，找到 Sonos 卡片。
- 点击 设备 (Devices)，你应该能看到你家里所有的 Sonos 音响列表。
添加到仪表盘 (Dashboard)：
- 点击左侧菜单 概览 (Overview)（或者你自定义的仪表盘）。
- 点击右上角的 笔形图标 (Edit Dashboard) 进入编辑模式。
- 点击右下角 + 添加卡片 (+ ADD CARD)。
- 搜索 媒体控制 (Media Control) 或直接找 媒体播放器。
- 在 实体 (Entity) 下拉框中选择你的 Sonos 音箱（例如 media_player.living_room）。
- 点击 保存 (Save)。
现在，你直接在 HA 首页就能控制 Sonos 的播放、暂停、音量调节以及多音响成组 (Group) 功能了。
💡 进阶技巧 (基于 2025.12 新特性)
在 Home Assistant 2025.12 版本中，自动化（Automation）的构建变得更加直观。你可以尝试以下简单自动化：
场景：回家自动播放音乐
- 进入 配置 ->自动化与场景 ->+ 创建自动化。
- 触发条件 (When)： 选择“状态”，实体选你的手机定位（如 person.你的名字），状态从“离家”变为“在家”。
- 执行动作 (Then)：
- 搜索并选择 媒体播放器 (Media Player)。
- 选择动作 播放媒体 (Play Media)。
- 选择你的 Sonos 音响。
- 在内容 ID 中填入你想听的电台 URL 或简单的播放指令。
- （更简单的做法）： 选择动作 媒体播放器: 开启 (Turn on)，Sonos 通常会恢复播放上次的内容。
❓ 常见问题排查
- Q: 找不到设备怎么办？
- A: 90% 是网络问题。重启路由器、Sonos 音响和 Home Assistant 主机。确保 HA 没有被防火墙拦截 UDP 1900 端口（这是发现协议）。
Q: 实体显示“不可用 (Unavailable)”？
- A: 检查 Sonos 是否断电或掉线。如果是 Docker 版 HA，再次确认容器网络模式是否为 host。
Q: TTS (文字转语音) 能用吗？
- A: 能。Sonos 完美支持 HA 的 TTS。在“开发者工具” -> “动作”中搜索 tts.speak 或 tts.google_translate_say (取决于你配置的TTS服务)，选择 Sonos 实体即可让它说话，例如“洗衣机洗完了”。
