开源工具装完电视黑屏:我的排障全过程复盘

原创2026-10-19 12:05:251,724 阅读
文章标签:智能硬件开发工具

开源工具装完电视黑屏:我的排障全过程复盘

给电视去广告、换启动器,是这两年 Android TV 玩家圈里最流行的一类操作。把一个纯 Python 写的 ADB 客户端、一张按品牌整理的 debloat.txt 禁用清单、再加一个原生 Java 实现的 tvOS 风格 Launcher 组合起来(正是 tv-vibehack 这个仓库在做的事),理论上一个下午就能让老电视脱胎换骨。

但"理论上"三个字,往往就是翻车的开始。我照着这个思路折腾一台小米电视时,就撞上了最经典的故障形态:命令全部执行成功、APK 也装上去了,按下 Home 键,屏幕直接黑掉,遥控器怎么按都没有反应。这篇文章就是我那次排障全过程的复盘——从"以为砖了"到逐层定位根因,再到最后发现黑屏其实是一连串可预测的小错误叠加出来的结果。

故障现象与第一反应

先描述一下现场。电视是小米 Mi TV 4A(Android TV 10,PatchWall 固件),原本的主页长这样:顶部是推荐横幅,往下是厂商塞进去的内容流和推广位。

小米电视原装主页,带推荐横幅与推广位

跑完去广告脚本、装好新 Launcher 之后,画面先是闪了一下,然后停在纯黑。Home 键无响应,方向键无响应,只有电源键还活着。第一反应当然是:是不是把系统桌面组件禁用坏了?

这里要庆幸一个设计:tv-vibehack 从第一天就把"可逆"写进了工具链。它的禁用操作统一走 pm disable-user --user 0,而不是 pm uninstall——被禁用的包只是对用户 0 不可见,系统分区里原封不动,随时可以 pm enable 拉回来(见 tools/disable.sh 的生成逻辑和 tools/restore.sh 的恢复逻辑)。所以哪怕屏幕黑着,只要 ADB 通道还在,就远没到"砖"的程度。

冷静下来的第一件事,是确认 ADB 还能不能连上电视。

逐层排查链路:从日志到固件

我把这次排查拆成了五层,每一层都有可能单独造成"黑屏",而实际故障往往是其中两三层同时踩坑的结果。

第一层:连接层——连不上就无从谈起

排查的第一步是确认设备在线。仓库里的 tools/tv.py 是一个不依赖官方 adb 二进制的纯 Python ADB 客户端,基于 adb_shell 实现。它连的是 5555 端口的 ADB-over-TCP:

export TV_HOST=192.168.1.50
tools/venv/bin/python -I tools/tv.py --probe   # 打印型号、Android 版本、固件 build

--probe 会通过 getprop 拉出 ro.product.model、ro.build.version.release、ro.build.display.id 等一整套设备信息。这一步如果报错,先别查电视,先查电脑——这个项目在 README 里专门记录过一个 macOS 上的坑:系统把 Google 签名的 adb 当作自己的应用,在"本地网络隐私"里静默拦截了连接,端口明明是通的,却一直报 No route to host。这也是为什么项目坚持用纯 Python 客户端绕开官方 adb。

连接层还有一个隐蔽陷阱:串联执行的 pm 命令可能静默中断。手动敲 adb shell "pm disable a; pm disable b",第二条可能根本没执行。所以 tools/tv.py 提供了 --batch 模式,从标准输入按行读取命令、每条独立发送:

printf 'cmd1\ncmd2\n' | tools/venv/bin/python -I tools/tv.py --batch

排查到这里,连接是通的,包管理命令也正常返回。问题不在这一层,往下走。

第二层:传输层——APK 装不进去也是黑屏的帮凶

接下来要确认 Launcher APK 是不是真的装上了。tv-vibehack 的安装脚本 launcher/build-and-install.sh 用的是 tools/b64push.py 来上传 APK——因为通过 Python 客户端的 push 上传大文件会挂起,所以它把文件切成 48 KiB 的块,base64 编码后塞进 echo ... >> 文件 的 shell 命令里传上去,最后用 md5sum 校验两端一致:

CHUNK = 48 * 1024  # raw bytes per shell command (base64 grows it by 4/3)
...
out = dev.shell(f"echo '{part}' >> {tmp} && echo ok{i}", read_timeout_s=60.0)
out = dev.shell(f"base64 -d {tmp} > {remote} && rm {tmp} && md5sum {remote}", read_timeout_s=120.0)

如果 APK 传输途中损坏,pm install 会失败,但脚本的 set -euo pipefail 不会帮你在电视端回滚——这就是为什么安装环节一定要看校验输出。我这次传输是正常的,APK 也确实装上了。继续。

第三层:操作顺序层——黑屏的真正元凶之一

装上之后,build-and-install.sh 依次做了四件事:

"pm install -r /data/local/tmp/tvhome.apk"
"pm grant com.gathin.tvhome android.permission.ACCESS_FINE_LOCATION"
"cmd package set-home-activity --user 0 com.gathin.tvhome"
"pm disable-user --user 0 $STOCK_LAUNCHER"

注意这个顺序:先安装新 Launcher、把它设为默认 Home,最后才禁用原装 Launcher。这是整个项目最重要的操作纪律,README 的 Gotchas 里白纸黑字写着:

Disable the stock launcher only after the new one is installed, or the Home button lands on a factory test app.

我的黑屏故障,一半就出在这:如果顺序反了(或者 set-home-activity 因为某种原因没生效),按 Home 键时系统找不到任何可用的 HOME intent 处理者,就会停在没有任何界面的黑屏状态。系统里装着十几个声明了 CATEGORY_HOME 的应用时,cmd package set-home-activity 是唯一能确定"谁来当桌面"的手段,这一步绝对不能省。

第四层:输入法层——黑屏之外的"第二现场"

排掉顺序问题后,界面回来了,但又冒出第二个症状:任何搜索框里都弹不出键盘。翻 examples/xiaomi-mi-tv-4a/debloat.txt 的文件头,里面明明白白写着这台电视固件的已知 quirk:

# Known quirk on this firmware: default_input_method points at com.baidu.input, which is not
# installed, so no keyboard appears in search fields. Set Gboard as the IME (see README gotchas).

固件的 default_input_method 指向一个根本没装进系统里的百度输入法。这类问题在换掉原装 Launcher 之后尤其明显——因为原装桌面可能自己兜底处理了输入,第三方 Launcher 则老老实实问系统"输入法是谁",然后就拿到了一个不存在的答案。修复也简单,一条 ime set 命令指回 Gboard:

tools/tv.py 'ime set com.google.android.inputmethod.latin/com.android.inputmethod.latin.LatinIME'

这台电视的 Debloat 清单里还顺手禁了 com.google.android.inputmethod.latin 之外的一堆东西(com.miui.tv.analytics 遥测、com.mitv.tvhome.atv 等 PatchWall 内容流、com.xiaomi.mitv.updateservice 更新服务),每一条都用注释标了用途。这种"清单即文档"的做法,是排障时最值钱的东西——你能精确知道是哪条命令改变了哪个行为。

第五层:Launcher 自身层——黑屏可能本来就是设计

最后回到新 Launcher 本身。它名叫 com.gathin.tvhome,在 AndroidManifest.xml 里声明了 HOME intent:

<intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.HOME" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

而它的主题在 styles.xml 里被设成了 android:Theme.Material.NoActionBar.Fullscreen,windowBackground 强制纯黑,布局根节点 activity_main.xml 的背景色也是 #FF000000——因为产品定位就是"Apple TV 4K 式纯黑主页",这是刻意设计而非故障。

但这里确实藏着一个容易被误判成"黑屏"的细节:MainActivity 把 onBackPressed 重写成了空实现(Home 界面按 Back 不做任何事),而且 launchMode="singleTask" + stateNotNeeded="true" 意味着它不做任何持久化、不记住任务栈。如果你恰好把它和原装桌面一起禁了、或者依赖 Back 键退出,就会在"看起来死机"的状态里打转。

所以排障的最后一层其实是问自己一句:当前这个黑,是"没有 Home 处理者"的黑,还是"我的 Launcher 启动后什么都没画"的黑? 前者是系统层问题,后者才是应用层问题。分辨方法很简单:黑屏时用 tools/tv.py 'pm list packages -d' 看禁用清单,再 tools/tv.py 'cmd package resolve-activity --brief -a android.intent.action.MAIN -c android.intent.category.HOME' 看系统此刻把 Home 解析给了谁。一条命令,两个世界。

最终根因与可复用的教训

复盘完整条链路,这台电视的"装完黑屏"其实是三件事叠加,任何一件单独发生都不致命:

  1. 顺序纪律被破坏:新 Launcher 尚未就位就把原装桌面禁用,导致系统没有任何 Home 处理者,按 Home 即黑屏;
  2. 默认 Home 未显式指定:多 HOME 应用并存时依赖系统自动选择,选错就落在奇怪的界面上;
  3. 输入法残留错误配置:default_input_method 指向未安装的包,换 Launcher 后暴露成"无键盘"。

好在整套工具链从设计上就是为翻车准备的,最终恢复也只用了两条命令:tools/restore.sh examples/xiaomi-mi-tv-4a/debloat.txt 把所有 pm enable 回去、把原装桌面重新 set-home-activity 并复位动画缩放(tools/restore.sh),然后按正确顺序重来一遍。恢复后的主页长这样,纯黑背景、顶部问候语与大号时钟、右侧 Inputs / Wi-Fi / Settings 三个磨砂药丸按钮、底部一条 Dock:

tv-vibehack 新版主页:纯黑背景、顶部时钟问候、磨砂药丸按钮与底部 Dock

原装与新的对比,一眼就能看出折腾的意义在哪里:

原装带广告主页与新 Launcher 主页的上下对比

把这次经验沉淀成一张可复用的检查清单,送给每一个准备给电视动手的人:

  • 备份先行:动手前把完整包列表、禁用列表、getprop 和全部设置存下来(这是 PROMPT.md 里写死的第一步,不是可选项);
  • 永远 disable,绝不 uninstall:pm disable-user --user 0 是唯一允许出现的操作,电视自身设置里都能手动还原;
  • 先装后禁,顺序不可倒置:安装新桌面 → set-home-activity → 验证能进主页 → 最后才禁用原装桌面;
  • 命令一条一发:别用分号串联 pm 命令,用 --batch 按行执行并逐条看输出;
  • 大文件走分块传输:APK 上传用 b64push.py 并在远端核对 md5;
  • 把输入法写进清单:换桌面后弹不出键盘,先查 default_input_method 指向谁,再决定禁不禁;
  • 黑屏先查 Home 解析:cmd package resolve-activity 的输出,比遥控器上的任何按键都诚实。

工具可以把老电视从广告里捞出来,但真正的护城河从来不是脚本本身,而是"出了事还能原路走回去"的设计。这次黑屏让我对这句话有了切身体会——折腾电视这件事,最贵的不是电视,是心态。而一份把每个坑都写进注释的 debloat 清单和一套可逆的恢复脚本,就是心态最好的保险。

登录后查看全文
cleanyourtv