故障排查
用于检查调试连接、安装和启动器切换的实用步骤。
找不到开发者选项
打开「设置」→「系统」或「设备偏好设置」→「关于」。连续按七次 Build 项目。不同厂商的名称可能不同。如果是受管理设备或运营商提供的设备，调试控制可能被固件锁定，此流程可能无法使用。不要继续修改路由器设置来解决固件限制。
电脑找不到电视
- 确认电视已开机，并且两台设备在同一个局域网。访客 Wi-Fi 或隔离的 IoT 网络可能会阻止设备互相访问。
- 在电视网络设置中重新确认当前 IP 地址。重启后地址可能会变化。
- 如果电视提供这些开关，请开启 USB 调试和网络/ADB 调试。留意电视上的授权对话框，只允许你信任的电脑。
- 部分 Google TV 型号使用无线调试配对码和临时端口，而不是立即开放 5555 端口。请按安装提示词中的配对步骤操作。
- 不要通过互联网路由器转发 ADB 端口。
在 macOS 上，「No route to host」可能由局域网隐私权限导致。源码包中包含 Python ADB 客户端作为替代方案；解压源码包后，先阅读 docs/TROUBLESHOOTING.md 的 Connecting 部分，再判断电视是否离线。
USB 音箱或硬盘停止工作
部分电视盒子在 USB 调试开启时会改变 USB 端口行为。完成操作后关闭调试，再次检查设备。日常使用启动器不需要保持调试开启。
启动器编译或 APK 安装失败
使用完整解压的源码包，不要只使用单独下载的 APK 或编译文件。准备 Python 3、JDK 17、Android SDK Platform 34 和 Android Build Tools 34.0.0。查看实际错误，不要通过关闭验证或安装无关 APK 来绕过问题。部分电视固件还会在安装过程中要求你在屏幕上确认。
解压源码包中的 README.md 和 docs/TROUBLESHOOTING.md 是编译前置条件和型号专属问题的参考资料。配套的 Windows 编译脚本和 macOS/Linux 编译脚本必须放到解压后的 launcher/ 目录。
Home 键仍然打开旧启动器
安装应用和把它设为 Home 所有者是两个不同步骤。先确认新启动器能正常打开。让助手检查实际处理 Home 的组件，并按照准确型号的说明操作。切换期间保留一个能用的启动器。不要因为某个系统软件包名称看起来有关联，就猜测或禁用它。
遥控器、音频、HDMI 或投屏发生变化
停止继续修改，并将最近的软件包修改与原始备份对比。这些功能可能依赖厂商服务。使用对应的恢复流程，然后分别测试每个功能。
流媒体应用仍然显示广告
这是正常现象。项目修改的是系统首页和选定的厂商服务，不会移除 YouTube、Netflix 或其他流媒体应用内部的广告，也不会移除订阅要求。
公开提交 issue 时应包含什么
提供电视型号、地区、固件版本、失败步骤和经过脱敏的错误信息。不要在公开报告中放入私人地址、设备标识符、调试密钥、凭据或完整备份。