从"用"到"造"

前面七篇讲的都是"用"：用工具连电视、禁应用、传文件。最后一篇往前多走一步，看 CleanYourTV 的"造"——launcher（新首页）与 add-on（附加模块）是怎么构建出来的，主题又是怎么推送到电视的。这一篇的主角是 docker-build.sh 与 theme.sh。

先说清楚定位：常规精简流程不需要你亲手构建——按第 3 章走，构建由流程自动完成，你拿到的就是可安装的产物。需要自己动手构建的，主要是想改 launcher 源码、想定制 add-on 的玩家。如果你是后者，这一篇就是入口。

docker-build.sh：把构建环境装进盒子

为什么需要 Docker

构建 launcher 与 add-on 需要一整套开发环境：JDK 17、Android SDK 34，外加各种构建工具。在本机装齐这套环境，对非开发者是场灾难——版本冲突、环境变量、下载源，每一步都能劝退新人。

docker-build.sh 的思路是把这套环境打包进 Docker 镜像：本机只需要装 Docker，构建在容器里进行，不污染你的系统，也不用你亲手配 JDK 与 SDK。镜像内的工具版本（JDK 17 + Android SDK 34）由项目固定，保证任何人构建出来的产物一致。

Docker 环境准备清单

工欲善其事，先确认盒子本身没问题。动手之前按清单过一遍：第一，电脑已安装 Docker——Windows 与 macOS 装 Docker Desktop，Linux 按发行版装对应引擎；第二，Docker 守护进程正在运行，终端里执行 docker --version 能看到版本号即算通过；第三，磁盘留出足够空间，镜像与构建产物都要占地方；第四，网络能拉取镜像，首次运行需要下载项目指定的构建镜像。四项齐备，docker-build.sh 才能把活干漂亮；任何一项缺失，脚本会在早期就报出来，按提示补即可。

两种用法

模式 命令形态 用途
完整构建 bash tools/docker-build.sh 在容器内编译 launcher / add-on，产出安装包
只装不构建 SKIP_BUILD=1 bash tools/docker-build.sh 安装场景：跳过编译，只准备容器与依赖

"装时用 SKIP_BUILD=1"是项目文档的明确建议：如果你只是按流程安装产物，不需要每次重新编译，加这个环境变量能省下可观的构建时间。（具体参数与行为以脚本注释和仓库 README 为准。）

执行与预期输出

  1. 确认 Docker 已安装且正在运行（在终端里能执行 docker --version 看到版本号）。
  2. 在项目根目录执行：
SKIP_BUILD=1 bash tools/docker-build.sh
  1. 预期看到：脚本拉取或复用镜像，在容器内完成准备工作，最后输出产物路径。首次运行会下载镜像与依赖，耗时取决于网络；二次运行会复用缓存，快得多。
  2. 若执行完整构建（不带 SKIP_BUILD=1），预期看到容器内的编译日志，结束后产出 launcher 与 add-on 的安装文件。

产物是什么

构建的落脚点是两样东西：

  • launcher：新首页的本体，装到电视上替换默认桌面。
  • add-on：附加模块，提供 launcher 之外的增强能力。

与产物相关的目录结构值得记住：themes/ 下放着二十一套主题，供首页换装；add-ons 在 addons/ 目录，不作为模块编入 launcher——也就是说 add-on 是独立可选的部分，装不装、装哪个，由你决定，launcher 本体不捆绑它们。这个边界让"最小安装"成为可能：只装 launcher，电视已经可用；需要什么增强，再按需取 add-on。

完整构建的旅程

不带 SKIP_BUILD=1 的完整构建，过程像一次小型旅行。脚本启动后，先在容器里准备好固定版本的工具链——JDK 17 加 Android SDK 34，版本由项目说了算，你无需操心；随后拉取或复用构建镜像，首次运行这一步最耗时，取决于你的网络；接着在容器内编译 launcher，如果你也需要 add-on，编译范围覆盖两者；最后产物落地，脚本把路径打印给你。整个过程你的本机除了 Docker 什么都不用装，编译在盒子里进行，干净也隔离。

二次构建会复用缓存，速度快得多。所以完整构建的真正成本集中在第一次，迈过那道门槛，后面就是轻车熟路。

构建产物怎么到电视上

构建或取得产物之后，最后一步是让它们上电视。这条路本书已经铺过：产物通常通过 ADB 通道推送安装——小文件用 tv.py 的 push 子命令，APK 这类大文件交给 b64push.py 分块上传并校验（ct-0404）；安装完成后，launcher 设为默认桌面，add-on 按需取用。如果你是在第 3 章的助手流程里，这一切由助手代劳，你只需在电视上确认安装对话框即可。两条路径到达的是同一站，区别只在谁按按钮。

flowchart TD
    A[docker-build.sh] --> B[Docker 容器 JDK 17 + SDK 34]
    B --> C[构建 launcher]
    B --> D[构建 add-on]
    C --> E[安装到电视]
    D --> E
    E --> F[theme.sh 推送 themes 下主题]
    F --> G[首页换装完成]

theme.sh：一键换装

它做什么

theme.sh 负责把 themes/ 目录里的主题推送到电视，让首页换个面貌。项目随附二十一套主题，从深色到浅色、从冷色到暖色，换装是改观成本最低的一招——不动任何功能，只改视觉。

使用步骤

  1. 连接就绪，tv.py 探活正常。
  2. 想好要推哪套主题（主题名以 themes/ 目录下的实际文件为准，可以先浏览目录挑一个）。
  3. 在项目根目录运行：
bash tools/theme.sh <主题名或主题文件>

（参数写法以脚本注释与 --help 为准。）

  1. 预期看到：推送完成的反馈；回到电视首页，外观已变为所选主题的配色与质感。想再换，换个名字再推，二十一套足够挑花眼。
  2. 主题与 launcher 的关系是"皮"与"骨"：launcher 提供结构与功能，主题只负责皮肤，所以换主题不会影响你的应用布局与配置，放心试。

二十一套主题怎么挑

面对二十一套主题，选择困难是常态。给两条务实建议：其一，按客厅光线挑——客厅亮、白天看片多，优先浅色或高对比主题，内容卡片更跳得出来；晚上关灯看片多，深色主题更护眼、也更融进环境。其二，按内容来源挑——如果你常用某个视频平台，选一套让该平台图标在首页最顺眼的即可，主题本就是为主内容服务的。挑选成本几乎为零：不满意，换个名字再推一次，随时可反悔。与其纠结，不如一周换一套，用不了多久就能找到你的本命主题。

构建侧常见问题

现象 排查方向
docker 命令找不到 Docker 没装或没加入 PATH，先装 Docker
镜像拉取失败 网络问题，稍后重试或配镜像加速（以你的环境为准）
构建中途报错 看容器内日志；工具版本以项目固定为准，别本机凑
SKIP_BUILD 后仍找不到产物 该模式本就不编译，产物来自仓库自带或上一步构建
主题推送成功但首页没变化 确认推的是 themes/ 下主题；重启电视再看

与全书流程的汇合

把第 4 章的工具串起来，一条完整的手动进阶路线是这样的：

  1. tv.py 打通连接（ct-0401）；
  2. recovery.py 留底（ct-0403）；
  3. disable.sh 执行禁用（ct-0402）；
  4. 需要时 b64push.py 传大文件、relay.py 牵桥（ct-0404）；
  5. 想定制时 docker-build.sh 构建、theme.sh 换装（本篇）；
  6. 固件升级后 check.py 核对、--fix 恢复（ct-0403）。

你会发现，这条路线和第 3 章助手走的路是同一个地图——工具就是流程，流程就是工具。这也是本书花整整一章讲 tools/ 的用意：看懂工具，你就看懂了这个项目的全部。

常见问题

问：完整构建一次要多久？

答：没有标准答案，取决于你的机器、磁盘和网络；首次要拉镜像，通常最久，之后有缓存会快很多。以你机器上的实际耗时为准，第一次建议留出充裕时间。

问：电脑上不想装 Docker，还能自己构建吗？

答：docker-build.sh 的设计前提就是本机有 Docker，没有它脚本无从搭起构建环境。不装 Docker 的读者，按第 3 章流程直接获取并使用现成产物即可，功能上没有任何缺失。

小结

docker-build.sh 把 JDK 17 + Android SDK 34 的构建环境装进 Docker，本机只需 Docker，安装场景记得用 SKIP_BUILD=1 跳过构建；theme.sh 一键推送二十一套主题，给首页换装。产出结构上记住一句话：launcher 是骨架，add-on 是可选增强（在 addons/，不编入 launcher），主题是皮肤。至此，第 4 章的全部工具就讲完了——连接、执行、记账、对账、传输、转发、构建、换装，各就其位，各司其职。