补充 OrangePi CM5 Android 13 实际编译踩坑记录与修复方法

1、Dockerfile 加入实测必需的兼容包：libncurses5（Clang 依赖）、python2（Rockchip U-Boot make.sh 硬依赖）、libssl-dev、imagemagick、protobuf-compiler 等预防性包 2、新增编译后的 U-Boot 手动修复步骤：-F 参数不自动生成 MiniLoaderAll 和 trust.img，需手动调用 u-boot/make.sh rk3588 + trust.img 副本伪装 + -Mu 重打包 3、新增完整镜像产物清单，说明 update.img 作为 Rockchip 固件打包格式已包含所有分区镜像，首次烧录只需 update.img 4、新增分区单独烧录对照表，指导开发调试时精确刷分区（boot/super/uboot 等）节省时间 5、新增 10 个踩坑速查表，覆盖 SDK 下载、合并、编译、打包全流程 6、新增新电脑复现完整命令流水线，换电脑后按序执行可避开所有已知坑 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-21 10:01:29 +08:00 · 2026-04-21 10:01:29 +08:00 · 75662e102e
commit 75662e102e
parent c21c4d2547
1 changed files with 244 additions and 17 deletions
--- a/远程开发操作指南.md
+++ b/远程开发操作指南.md
@ -467,11 +467,14 @@ rm Android_13.tar.gz
 # rm Android_13.tar.gz Android_13.tar.gz0*
 ```

-### 3.7.6 创建 Dockerfile
+### 3.7.6 创建 Dockerfile（含所有踩坑补丁，实测可用版）

 Dockerfile 位于虚拟机 `~/OrangePi_CM5/docker/Dockerfile`，基于 Ubuntu 22.04。
+官方文档 7.2 的依赖列表不完整，本版本已加入所有实际踩坑后补齐的包。

 ```dockerfile
+# OrangePi CM5 Android 13 编译环境
+# 基础镜像：Ubuntu 22.04（符合 OrangePi 官方推荐环境）
 FROM ubuntu:22.04

 # 清华镜像源
@ -482,6 +485,9 @@ ENV DEBIAN_FRONTEND=noninteractive
 ENV TZ=Asia/Shanghai
 RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

+# 启用 i386 多架构（Android 编译需要 32 位兼容库）
+RUN dpkg --add-architecture i386
+
 # 官方文档 7.2 要求的编译依赖
 RUN apt-get update -y && apt-get install -y \
    git gnupg flex bison gperf build-essential \
@ -493,9 +499,25 @@ RUN apt-get update -y && apt-get install -y \
 # Android 13 需要 OpenJDK 11
 RUN apt-get install -y openjdk-11-jdk

+# 【踩坑 1】Ubuntu 22.04 默认没有 libncurses.so.5
+# 但 Android 预编译 Clang 工具链依赖它，不装会导致编译到 40+ 分钟时报错
+RUN apt-get install -y libncurses5 libncurses5:i386
+
+# 【踩坑 2】Ubuntu 22.04 编译 Android 可能需要的预防性包
+RUN apt-get install -y \
+    libssl-dev pkg-config m4 imagemagick \
+    python-is-python3 python3-protobuf \
+    protobuf-compiler libprotobuf-dev \
+    libncurses-dev
+
+# 【踩坑 3】Rockchip U-Boot 的 make.sh 硬依赖 Python 2
+# 不装会导致 MiniLoaderAll 合成阶段报 "ERROR: No python2"
+RUN apt-get install -y python2 python2-dev python2.7
+
 # 辅助工具
 RUN apt-get install -y python3 python3-pip rsync cpio bc kmod \
-    device-tree-compiler liblz4-tool lzop sudo vim nano
+    device-tree-compiler liblz4-tool lzop sudo vim nano \
+    fontconfig schedtool

 RUN apt-get clean && rm -rf /var/lib/apt/lists/*

@ -545,30 +567,157 @@ sudo docker run -it \

 推荐全量编译命令：
 ```bash
-# 容器内执行
+# 容器内或后台 docker run -d 执行
 ./make.sh -FMu -b orangepicm5 --gapps
 ```

-编译耗时：**约 3-6 小时**（取决于 CPU 核心数和内存）。
-
-### 3.7.10 验证编译结果
-
-成功后生成 `update.img`：
+实测耗时：**6 小时 11 分钟**（VMware 虚拟机 8 核 20GB RAM + 9GB Swap）。

+推荐后台执行（避免 SSH 断开中断）：
 ```bash
-cd rockdev/Image-rk3588s_t
-ls update.img
-# 预期看到 update.img 文件
+sudo docker run -d --name orangepi-build \
+  -v /home/zhangwenqi/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13:/workspace \
+  -w /workspace \
+  android-builder-orangepi:13.x \
+  bash -c 'echo 开始: $(date) > /tmp/build.log && \
+    ./make.sh -FMu -b orangepicm5 --gapps >> /tmp/build.log 2>&1; \
+    echo 结束: $(date) exit=$? >> /tmp/build.log'
+
+# 查看进度
+sudo docker exec orangepi-build tail -20 /tmp/build.log
+sudo docker exec orangepi-build du -sh /workspace/out/
 ```

-其他镜像文件也在 `rockdev/Image-rk3588s_t/` 目录。
+### 3.7.10 编译后的 U-Boot 修复（实测必需）

-### 3.7.11 烧录到开发板
+**`-F` 参数理论上会编译 U-Boot，但实际只产出 `u-boot.img` 等基础文件，
+不会自动调用 Rockchip 脚本合成 `MiniLoaderAll.bin` 和 `trust.img`。**

-1. 将 `update.img`（或其他镜像）拷贝到 Windows
-2. 使用 **RKDevTool** 瑞芯微烧录工具
-3. OrangePi CM5 进入 Loader 模式（按住 MaskROM/Recovery 键上电）
-4. 加载 `update.img` 一键烧录
+如果 `make.sh -FMu` 最后日志中出现：
+```
+u-boot/trust.img not fount! Please make it from u-boot first!
+u-boot/*MiniLoaderAll_*.bin not fount! Please make it from u-boot first!
+Error:<AddFile> open file failed,err=2!
+Make firmware FAILED
+```
+
+需要手动执行两步修复：
+
+**修复步骤 1：合成 Rockchip U-Boot（生成 MiniLoaderAll + uboot.img 新版）**
+
+```bash
+# 启动临时容器执行 u-boot/make.sh rk3588
+sudo docker run --rm \
+  -v /home/zhangwenqi/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13:/workspace \
+  -w /workspace/u-boot \
+  android-builder-orangepi:13.x \
+  ./make.sh rk3588
+```
+
+成功标志：
+```
+Image(no-signed, version=0): uboot.img (FIT with uboot, trust...) is ready
+Image(no-signed): rk3588_spl_loader_v1.13.xxx.bin (with spl, ddr...) is ready
+```
+
+**修复步骤 2：创建 trust.img 符号文件（新版 Rockchip 已将 trust 合并到 uboot.img）**
+
+```bash
+# 在虚拟机宿主机执行（非容器内）
+cd ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13/u-boot/
+sudo cp -a uboot.img trust.img
+```
+
+**修复步骤 3：重新打包（跳过编译，只做 mkimage + update.img）**
+
+```bash
+sudo docker run --rm \
+  -v /home/zhangwenqi/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13:/workspace \
+  -w /workspace \
+  android-builder-orangepi:13.x \
+  ./make.sh -Mu -b orangepicm5 --gapps
+```
+
+`-Mu` 只做"生成分区镜像 + 打包 update.img"，不重新编译 Android，耗时约 5-10 分钟。
+
+### 3.7.11 验证编译结果
+
+成功后在 `rockdev/Image-rk3588s_t/` 目录生成所有镜像：
+
+```bash
+ls -lh ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13/rockdev/Image-rk3588s_t/
+```
+
+预期产物（实测）：
+
+| 文件 | 大小 | 分区/作用 |
+|------|------|----------|
+| **update.img** | **2.3GB** | eMMC/TF 卡完整固件（首要烧录目标） |
+| **update_spi_nvme.img** | **2.3GB** | SPI Flash + NVMe SSD 组合烧录 |
+| MiniLoaderAll.bin | 465KB | bootloader 加载器（MaskROM 引导） |
+| uboot.img | 4.0MB | U-Boot（已内含 trust） |
+| trust.img | 4.0MB | Trust 镜像（副本，兼容脚本） |
+| boot.img | 37MB | 内核 + ramdisk（boot 分区） |
+| recovery.img | 47MB | Recovery 模式镜像 |
+| super.img | 2.2GB | 超级分区（含 system+vendor+odm+product） |
+| dtbo.img | 443B | 设备树 Overlay |
+| resource.img | 2.5MB | 内核资源（开机动画、字体等） |
+| vbmeta.img | 4KB | 验证启动元数据 |
+| misc.img | 48KB | 其他信息分区 |
+| baseparameter.img | 1MB | 显示屏参数 |
+| parameter.txt | - | 分区表定义 |
+
+### 3.7.12 烧录到 OrangePi CM5 开发板
+
+#### 首次烧录：只需 update.img
+
+**`update.img` 是完整的 Android 13 系统固件**，包含所有分区镜像。
+烧录 update.img 会一次性写入所有分区，等于给开发板全新刷系统。
+
+烧录步骤：
+1. 从虚拟机拷贝 `update.img`（2.3GB）到 Windows 电脑：
+   ```bash
+   # Mac 或虚拟机上执行（假设通过 Tailscale SSH）
+   scp zhangwenqi@100.123.82.91:/home/zhangwenqi/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13/rockdev/Image-rk3588s_t/update.img ~/Desktop/
+   ```
+
+2. Windows 电脑下载并安装 **RKDevTool**（瑞芯微官方烧录工具）
+
+3. OrangePi CM5 进入 **MaskROM 模式**：
+   - 按住板子上的 **Recovery / MaskROM 按键**
+   - 插入 USB 线到电脑
+   - 松开按键
+
+4. RKDevTool 界面切换到 **升级固件** 标签
+
+5. 点击 **固件** 按钮，选择 `update.img`
+
+6. 点击 **升级** 按钮，等待烧录完成（约 2-5 分钟）
+
+7. 烧录完成后开发板自动重启进入 Android 13
+
+#### 镜像文件说明与高级烧录
+
+`update.img` = Rockchip 打包格式，内部已包含所有其他 `.img` 文件。
+单独的 `.img` 文件是给**开发调试**用的，用途：
+
+| 场景 | 用哪个镜像 | 烧录方式 |
+|------|-----------|---------|
+| 首次刷机 / 完整升级 | `update.img` | RKDevTool 升级固件 |
+| 只调试内核 | `boot.img` | `fastboot flash boot boot.img` |
+| 只更新系统 | `super.img` | `fastboot flash super super.img` |
+| 只更新 U-Boot | `uboot.img` | `fastboot flash uboot uboot.img` |
+| 只刷 Recovery | `recovery.img` | `fastboot flash recovery recovery.img` |
+| 改开机画面 | `resource.img` | `fastboot flash resource resource.img` |
+| SPI Flash + NVMe 设备 | `update_spi_nvme.img` | RKDevTool 升级固件 |
+
+**日常开发推荐**：
+- 改内核 / 驱动 → 单独烧 `boot.img`（几秒到 1 分钟）
+- 改应用 / 系统框架 → 单独烧 `super.img`（1-2 分钟）
+- 改 Bootloader → 单独烧 `uboot.img` + `MiniLoaderAll.bin`
+- 不确定或要彻底刷新 → 烧 `update.img`（2-5 分钟）
+
+这样可以避免每次修改都重刷整个系统。

 ### 3.7.12 关键差异对比（与 Radxa CM5）

@ -597,6 +746,84 @@ sudo docker start -ai orangepi-build
 sudo docker rm -f orangepi-build
 ```

+### 3.7.14 踩坑速查表（完整编译流水线）
+
+以下所有坑都是实际编译过程中踩到的，新电脑按文档 3.7.1~3.7.12 操作时**严格按顺序**可以避开。
+
+| # | 阶段 | 现象 | 根因 | 解决方法 |
+|---|------|------|------|----------|
+| 1 | SDK 校验 | gz03 分卷 MD5 校验通过但解压到 46GB 报 `invalid compressed data` | 百度网盘下载过程中该分卷损坏，但上游 md5sum 正好是损坏版本的 MD5 | 重新从百度网盘下载 gz03，对比同网盘其他用户汇报的 MD5 |
+| 2 | SDK 合并 | 官方文档推荐的 `cat ... \| tar -xzf -` 管道式解压在分卷边界处出错 | 管道模式下 tar 无法定位错误位置 | 改用"先合并成单文件 → 再解压"两步法 |
+| 3 | 构建镜像 | Android ninja 42 分钟时报 `libncurses.so.5: cannot open shared object file` | Ubuntu 22.04 默认只有 libncurses.so.6 | Dockerfile 装 `libncurses5 libncurses5:i386` |
+| 4 | 主体编译 | 6 小时编译完成后打包失败：`u-boot/trust.img not fount` | `make.sh -F` 只跑 U-Boot 编译，没调用 Rockchip 合成脚本 | 手动 `cd u-boot && ./make.sh rk3588` |
+| 5 | U-Boot 合成 | Rockchip make.sh 报 `ERROR: No python2` | Ubuntu 22.04 没 Python 2（默认只有 python3） | Dockerfile 装 `python2 python2-dev python2.7` |
+| 6 | 打包阶段 | mkimage.sh 找不到 `trust.img` | 新版 Rockchip 把 trust 合并到 uboot.img，不单独生成 | `cp uboot.img trust.img`（副本伪装） |
+| 7 | 打包阶段 | 手动 lunch 后执行 mkimage.sh 编译目标变成 `aosp_arm` | OrangePi make.sh 内部根据 `-b orangepicm5` 设置 lunch，手动设不对 | 直接用 `./make.sh -Mu -b orangepicm5 --gapps` 打包 |
+| 8 | 资源管理 | Soong 阶段内存峰值 19GB，会耗 Swap | Android 构建系统需要巨大内存 | 虚拟机分配 **20GB 内存 + 9GB Swap**（已配） |
+| 9 | 编译效率 | 编译中断重启后重新跑全部阶段 | 未保留 out/ 缓存 | 不要 `rm -rf out/`，重启时 make.sh 会增量继续 |
+| 10 | Docker 默认源 | `docker build` 拉 `ubuntu:22.04` 超时 | Docker Hub 国内访问慢 | `/etc/docker/daemon.json` 配置镜像加速器 |
+
+### 3.7.15 完整编译流水线（新电脑复现）
+
+如果换新电脑后需要重新编译，按以下顺序：
+
+```bash
+# === 准备阶段 ===
+# 1. 恢复 SDK 分卷到 ~/OrangePi_CM5/Aandroid_OrangePi/archive/
+# 2. MD5 校验所有分卷
+cd ~/OrangePi_CM5/Aandroid_OrangePi/archive
+md5sum -c md5sum
+
+# 3. 合并成单文件到 merged/
+cd ..
+cat archive/Android_13.tar.gz00 archive/Android_13.tar.gz01 \
+    archive/Android_13.tar.gz02 archive/Android_13.tar.gz03 \
+    archive/Android_13.tar.gz04 archive/Android_13.tar.gz05 \
+    archive/Android_13.tar.gz06 archive/Android_13.tar.gz07 \
+    archive/Android_13.tar.gz08 > merged/Android_13.tar.gz
+
+# 4. 解压源码
+cd merged && tar -xzf Android_13.tar.gz
+
+# === 编译阶段 ===
+# 5. 构建 Docker 镜像（按 3.7.6 的 Dockerfile）
+cd ~/OrangePi_CM5/docker
+sudo docker build -t android-builder-orangepi:13.x .
+
+# 6. 主体编译（后台，约 6 小时）
+sudo docker run -d --name orangepi-build \
+  -v ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13:/workspace \
+  -w /workspace \
+  android-builder-orangepi:13.x \
+  bash -c './make.sh -FMu -b orangepicm5 --gapps > /tmp/build.log 2>&1'
+
+# 7. 等主体编译完成（会报 trust.img 缺失，正常）
+
+# === 修复阶段 ===
+# 8. 手动合成 Rockchip U-Boot
+sudo docker run --rm \
+  -v ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13:/workspace \
+  -w /workspace/u-boot \
+  android-builder-orangepi:13.x \
+  ./make.sh rk3588
+
+# 9. 创建 trust.img 伪装
+sudo cp -a ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13/u-boot/uboot.img \
+       ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13/u-boot/trust.img
+
+# 10. 只打包（复用已编译产物，约 5-10 分钟）
+sudo docker run --rm \
+  -v ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13:/workspace \
+  -w /workspace \
+  android-builder-orangepi:13.x \
+  ./make.sh -Mu -b orangepicm5 --gapps
+
+# === 完成 ===
+# 11. 验证 update.img
+ls -lh ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13/rockdev/Image-rk3588s_t/update.img
+# 预期：2.3GB
+```
+
 ## 3.8 Linux 虚拟机共享 Windows VPN（外网访问）

 虚拟机通过 VMware 桥接网络使用 Windows 的 Clash 代理上外网。已配置开机自动生效。