手里同时有两三块 RK3568 开发板的人多少都经历过同一个阶段Lightup 成功之后系统跑着跑着想要改点东西然后发现自己连“怎么把镜像烧回去”这个基本功都没完全吃透。尤其是 OpenHarmony 这类从源码编译到最终镜像落地链路较长的系统中间任何一个环节出了差错浪费的不是几分钟而是一整天的编译时间加一整块写坏的 userdata 分区。这篇内容我按自己实际走过的一套流程来写核心是 OpenHarmony 5.1 在 RK3568 开发板上的完整烧录路径从源码编译到镜像写入拆成 6 个可执行的实战步骤。每个步骤里除了“该怎么做”我还尽量把“为什么要这么做”和“翻车时怎么排查”一起讲清楚。适合手里有 RK3568 开发板、准备从 AOSP 或者纯 Linux 转向 OpenHarmony 的开发者也适合那些已经能跑起官方镜像、但想自己编译一版固件的工程师参考。1. 选板先看接口RK3568 为什么是 OpenHarmony 烧录场景里的主力板1.1 RK3568 和 RK3566 的差异选错板子会影响整个烧录流程很多人第一次接触 RK3568 都是从“RK3568 和 RK3566 到底有什么区别”这个问题开始的。这两个 SoC 同属瑞芯微的 356x 系列都是四核 Cortex-A55GPU 也都是 Mali-G52光看核心配置几乎一样。但真正落到开发板烧录和后续外设调试上差距就很明显了。RK3568 比 RK3566 多了 PCIe 3.0 控制器原生支持 PCIe 转 SATA 或者 PCIe 网卡扩展同时 RK3568 的以太网接口通常支持千兆 MAC配合外部 PHY 可以稳定跑满千兆。而 RK3566 更偏向低成本平板和交互屏方案多数 RK3566 开发板只带百兆网口或者干脆走 WiFi。这个差异对 OpenHarmony 开发意味着什么OpenHarmony 的分布式软总线、远程调试、日志导出等场景都依赖网络。你用 RK3568 板子做设备联调千兆网口在编译产物推送、NFS 挂载、日志抓取时快得不是一点半点。而且 OpenHarmony 标准版默认固件里很多调测工具和 hdc 传输都走网络通道网口带宽吃紧时整个开发体验都会变差。所以如果你还没下单直接选 RK3568 而不是 RK3566。这个建议不是性能党较真而是烧录之后长期开发的舒适度问题。RK3566 能跑 OpenHarmony 吗能但外设适配和网络瓶颈会让你多踩一堆没必要的坑。1.2 板载存储、电源与 USB 口决定了烧录一次要折腾多久确认了 RK3568 之后还要看具体开发板的存储和接口配置。我手头有几类不同配置的 RK3568 板子烧录体验差别很大。存储方面建议选带eMMC 32GB以上的型号。虽然也可以从 SD 卡启动系统但 OpenHarmony 的镜像包含 boot、system、vendor、userdata 等多个分区8GB eMMC 在编译后的镜像稍大一点就放不下。而且每次从 SD 卡启动调试时还要注意 SD 卡和 eMMC 的启动优先级问题容易混淆当前到底从哪里启动。电源更是不容易被注意到的坑。RK3568 开发板绝大多数用 DC 12V 供电少数支持 USB PD 供电。烧录过程中虽然不会高负载跑应用但如果你用的是劣质 Type-C 线供电电压跌落可能导致烧录中途设备掉线。RKDevTool 的典型死法就是烧录到一半日志窗口卡住不动十次里有七次是供电不稳定。USB 口主要影响烧录速度和稳定性。RK3568 开发板上的 USB 烧录口一般是 Type-C 或者 Micro USB建议用USB 3.0 接口连接电脑。实际测试中USB 2.0 接口在烧录单个 2GB 的 system.img 时耗时明显更长且更容易因线缆质量差导致传输中断。数据传输线尽量用短而粗的屏蔽线这点在 Windows 平台上尤其重要因为 Windows 下的 USB 驱动碰到传输错误后不会自动恢复必须重新插拔设备。2. 编译之前的环境三件事Ubuntu 版本、Python 版本、repo 初始化顺序2.1 磁盘、内存和 CPU 核数在真实编译中的硬指标OpenHarmony 5.1 的源码编译不是小工程。官方推荐的 Ubuntu 版本跨度很大但实战中我建议用Ubuntu 20.04 x86_64兼容性最省心。Ubuntu 22.04 也可以跑通全流程但部分老版本编译工具链对 GCC 的版本有隐晦要求出现问题时排查成本高。磁盘空间是第一个硬指标。完整的 OpenHarmony 源码加上编译产物至少需要200GB 可用空间我习惯预留 300GB。为什么这么大OpenHarmony 每个仓库都是一份完整的 git 历史repo sync 全量同步后.git目录本身就能占据一半空间。而编译过程的中间产物out 目录体积也相当可观单是 build 生成的文件就可能超过 60GB。你如果只有一个 256GB 的根分区编译到一半磁盘满会直接把构建进程杀掉而且是那种没有任何友好提示的杀法。内存方面16GB 是底线32GB 比较舒服。编译过程中 Ninja 和 GCC 会并发启动大量进程内存不足时表现为系统卡死、SWAP 暴增最后编译报错。如果你只有 16GB建议编译前把浏览器、IDE 全部关掉或者直接用build.sh --ccache之外再限制并发数比如设置ninja任务数减半。CPU 核数越多越好8 核 CPU 编译完整标准版大约需要 40 到 60 分钟16 核可以压到 25 分钟左右。2.2 repo 初始化与 manifest 分支千万别手滑拉成 masterOpenHarmony 源码使用repo工具管理。标准流程是先用 apt 安装 repo或者从 Android 源码工具链里拷贝一份 repo 脚本。接着执行mkdir ohos cd ohos repo init -u https://gitee.com/openharmony/manifest.git -b OpenHarmony-5.1-Release repo sync -c --no-tags这里最关键的是-b参数。我见过不少新手直接把分支写成master结果拉下来的是滚动开发版编译出来的系统不稳定烧到板子上各种诡异问题。做实际项目一定要锁定发布分支或 Release tag比如OpenHarmony-5.1-Release。repo sync本身就是个大工程依赖网络状况可能持续半小时到数小时。国内网络访问 Gitee 一般没问题但如果你的服务器不在国内建议配置 Gitee 镜像或者适当调高 git 的 http.postBuffer 和 http.lowSpeedLimit。实际操作中我习惯给 repo 命令加上-j8并发同步但要随时观察日志有些仓库因为网络抖动失败后 repo 会直接报错退出需要重新执行 sync。2.3 默认 Python 3.8 与编译辅助包的坑Ubuntu 20.04 自带 Python 3.8.10这个版本在 OpenHarmony 5.1 的构建体系里是能正常工作的。如果你的系统是 Ubuntu 22.04默认 Python 是 3.10建议直接用 apt 装一个Python 3.8或者用update-alternatives把默认 Python 切到 3.8。原因在于 OpenHarmony 的部分编译脚本和工具对 Python 小版本有兼容性要求。Python 3.10 在语法检查时会有DeprecationWarning平时无伤大雅但某些脚本里如果开启了严格的-W error编译会直接失败。编译辅助包方面Ubuntu 20.04 下需要预先安装binutils、file、git、curl、zip、unzip、default-jdk等基本工具。OpenHarmony 还会用到nodejs、npm做前端相关的资源编译好在build.sh会在首次运行时自动拉取依赖不需要你手动配置太完整的环境。唯一的建议是不要用系统自带的 Node 版本做干扰保持系统环境干净。3. 从源码到镜像的编译链路build.sh、产品配置与四类关键输出物3.1 product-name 为什么必须写 rk3568OpenHarmony 的编译入口是根目录下的build.sh或者是新版本提供的hb工具。编译命令很简单./build.sh --product-name rk3568 --ccache--product-name rk3568指定了产品配置这个参数决定了编译出来的系统包含哪些组件、默认启动哪个 Launcher、启用哪些内核模块。如果你用的是第三方开发板厂商适配的源码product-name 可能会是rk3568_xxx之类的自定义值具体先查看源码根目录下vendor/和product/目录中定义的 product 列表。如果参数写错编译过程一般会直接报错并列出可用的 product-name。这里要注意的是OpenHarmony 不像安卓那样可以在编译后通过 fastboot 随便改 product 分区所以 product-name 选错就得重新编译。白等一小时这种事我干过不止一次。3.2 编译过程的加速手段ccache、增量编译和内存策略编译一个大系统最影响心情的就是反复全量编译。OpenHarmony 支持 ccache上面命令里的--ccache参数会启用缓存第二次编译时能明显加快速度。第一次编译后ccache缓存通常能占据 10GB 到 20GB 空间这也在前面说磁盘要预留 300GB 的原因之一。如果你改动的只是某个子系统比如想改一下窗口管理框架不需要重新全量编译。OpenHarmony 的构建系统会基于 Ninja 做增量编译./build.sh再次执行时自动只编译变更部分。大部分情况下增量编译只需要几分钟但如果改动涉及底层内核头文件或者 HDF 驱动框架可能仍然触发大范围重编这是正常的依赖扩散。内存不足的应急方案是设置环境变量限制并发export NINJA_NUM_JOBS4 ./build.sh --product-name rk3568这会让编译慢一些但能防止进程被 OOM killer 干掉。大招是搞一个 swap 文件备用不要依赖系统默认的 2GB swapOpenHarmony 编译期间内存吃紧时16GB 交换分区的体验会好很多。3.3 输出镜像分工boot、system、vendor、userdata 到底谁是谁编译结束之后所有可烧录的镜像都集中在out/rk3568/packages/phone/images/目录。我第一次走完编译流程时看到这一堆文件名是懵的这里列个表帮新手快速对照镜像文件分区名主要作用烧录必要性boot_linux.imgboot内核与 ramdisk负责系统拉起必须烧录system.imgsystem系统核心服务、框架、预装应用必须烧录vendor.imgvendor硬件适配、HDF 驱动、厂商私有库必须烧录userdata.imguserdata用户数据分区出厂通常是空文件建议烧录uboot.imgubootU-Boot 引导程序视情况如果你改了 bootloader 才需要resource.imgresource内核资源文件、logo 等改开机动画/logo 时需要parameter.txt-分区表配置文件配合 RKDevTool 烧录时使用日常迭代中最快的烧录方式是只烧boot_linux.img、system.img、vendor.img三个文件userdata 不烧保留开发板上的用户数据和测试应用。如果你改了 U-Boot 或者设备树相关的 bootloader 配置就要把uboot.img和resource.img也一起烧录否则会出现“系统起不来但你又不知道是内核问题还是引导问题”的尴尬情况。4. 把开发板送进烧录模式Loader 和 MaskRom 两种状态的触发原理4.1 进入烧录模式三种方法每种都有自己的适用场景RK3568 开发板支持两种底层烧录模式Loader 模式和MaskRom 模式。理解它们的区别能帮你少走很多弯路。Loader 模式是开发板 U-Boot 已经被执行的情况下进入的烧录状态。当 U-Boot 检测到 USB 烧录请求会暴露一个 Rockchip USB 设备给电脑电脑端工具就可以读写各个分区。这是最推荐的日常烧录模式操作简单不需要擦除整个系统。进入 Loader 的方法很直接USB 线连接电脑和开发板的烧录口按住板子上的Loader/Recovery 按键再插上 DC 电源通电。部分开发板设计不一样可能需要先按住按键再按复位键具体看板卡丝印说明。通电后保持按键 2 秒左右再松开电脑上如果安装了驱动会识别出一个 Rockchip USB Loader 设备。MaskRom 模式是最后的手段。当板子的 U-Boot 损坏、分区表被清空、或者系统完全无法启动时RK3568 会退回芯片内部的 MaskRom 引导代码等待 USB 设备枚举。进入 MaskRom 的操作通常是按住MaskRom 键某些板子是短接 eMMC 附近的测试焊点再上电。此时电脑识别到的设备名通常会变成Rockchip MaskROM或者Class for rockusb devices。这两种模式的核心区别是Loader 模式保留了完整的烧录分区接口烧录错误顶多导致系统起不来但还有救MaskRom 模式则可以从底层完全重刷甚至能救回被写坏的 bootloader。日常切换系统直接 Loader板子彻底变砖才需要 MaskRom。4.2 Windows 驱动识别失败与 Linux 下 upgrade_tool 的使用差异在 Windows 上烧录 OpenHarmony 镜像最常见的是先安装瑞芯微官方驱动DriverAssistant再安装RKDevTool烧录工具。驱动安装完成后插上板子设备管理器里应当能看到Rockchip USB Loader设备。如果设备出现在“未知设备”里多半是驱动签名问题。Windows 10/11 需要进入高级启动关闭“驱动程序强制签名”再重新安装一次驱动。如果你和我一样更习惯在 Linux 下做全流程烧录工具完全不需要 GUI。RK 官方为 Linux 提供了upgrade_tool老牌开源工具里还有rkdeveloptool。Linux 下安装工具之后先确认 USB 设备权限sudo chmod 666 /dev/bus/usb/*/* upgrade_tool ldld命令列出当前连接的设备能列出设备说明驱动识别没问题。upgrade_tool的烧录逻辑和 RKDevTool 完全一致只是全程命令行操作适合集成到自动化脚本里。比如写一个一键烧录脚本把编译产物和分区配置丢进去以后每次编译完直接跑脚本就能烧录不用打开 Windows 图形界面反复点击。5. 镜像写入的完整操作分区表、地址偏移和逐步烧录5.1 RKDevTool 与 upgrade_tool 的基本烧录操作无论用哪个工具烧录的本质都是把编译产物按照分区表写入 eMMC 的不同偏移地址。Windows 下的 RKDevTool 界面里有一列“地址”一列“文件”看起来复杂其实背后对应的就是瑞芯微分区表。RKDevTool 的烧录步骤一般是设备进入 Loader 模式后软件会自动刷新设备列表。然后在分区列表里添加需要烧录的镜像每一项对应一个起始地址。工具栏上有“执行”按钮点击后开始逐项写入。整个过程有进度条烧完后工具会提示“烧录成功”并自动复位设备。Linux 下upgrade_tool的对应操作是分区烧录upgrade_tool uf out/rk3568/packages/phone/images/parameter.txt upgrade_tool di -b out/rk3568/packages/phone/images/boot_linux.img upgrade_tool di -s out/rk3568/packages/phone/images/system.img upgrade_tool di -v out/rk3568/packages/phone/images/vendor.imguf表示先烧录分区表di表示写单个镜像-b、-s、-v分别代表 boot、system、vendor。实际使用中分区表不用每次烧录如果你改过分区大小才需要重新写入。只更新 system 或 boot 的话直接对应烧单个文件就行。5.2 分区表、地址偏移与烧录配置的对应关系parameter.txt是理解整个烧录过程的钥匙。打开这个文件你会看到类似这样的内容CMDLINE: mtdpartsrk29xxnand:0x000020000x00004000(uboot),0x000020000x00006000(misc),...这行文本定义了每个分区在 eMMC 中的起始地址和大小。地址单位是 sector每个 sector 512 字节。比如0x00004000表示从 8MB 偏移处开始放 uboot 分区。RKDevTool 里显示的“地址”列并不是 sector 偏移而是字节偏移通常是 sector 数值乘以 512 之后的结果。烧录时如果发现镜像写入后系统启动异常一个常见原因就是分区表与实际开发板 eMMC 大小不匹配。部分低配开发板 eMMC 是 8GB而默认 parameter.txt 可能是为 16GB 或 32GB 设计的userdata 分区会超出物理容量。这种情况下烧录器会报错或者静默截断表现为系统能起来但用户空间只有几百 MB。解决方法是针对板子的实际容量修改 parameter.txt 中的 userdata 分区大小或者使用厂商提供的对应容量配置。5.3 烧录成功的几个关键判定信号烧录完成不等于烧录成功。判断是否真正烧进去我有三个验证步骤第一看工具日志。RKDevTool 和 upgrade_tool 每一步都会打印类似Write LBA: 0x...的信息最后出现Reset Device OK之类的字样才表示设备被成功复位并尝试重启。第二观察开发板串口日志。如果板子有调试串口用串口线连接后应该能看到 U-Boot 打印信息随后是内核日志、init 进程日志。能看到OpenHarmony标志或者 hdc 服务启动日志就说明镜像烧录没问题系统正在正常引导。第三等系统稳定后执行hdc shell进入设备终端查看系统版本hdc shell param get const.product.name param get const.ohos.version能正确返回rk3568和5.1.0类似的信息说明当前系统确实是编译出来的那套环境而不是板子出厂自带的旧固件。6. 一次烧录失败“卡启动”的完整排查过程6.1 现象描述与日志抓取从 U-Boot 卡住到内核 panic这里分享一次比较典型的烧录失败排查。某块板子烧录成功后上电只亮电源灯HDMI 无输出串口日志最后一行停在 U-Boot 阶段没有任何内核启动信息。我第一步确认烧录地址。重新打开 RKDevTool对照parameter.txt里的 uboot 分区地址确认烧录uboot.img时用的地址没有填错。这一步没问题。第二步检查的是 U-Boot 能否识别到存储介质。串口日志里如果 U-Boot 已经打印了 eMMC 初始化成功的信息说明 U-Boot 阶段正常问题大概率在内核或者设备树。如果 U-Boot 卡住很可能是uboot.img和板子的 DDR 配置不匹配。RK3568 的 U-Boot 针对不同 DDR 频率有不同配置用错配置会导致 U-Boot 初始化内存时挂死。解决办法是从板卡厂商那里获取配套的 U-Boot 源码重新编译或者直接用同一厂商发布的预编译uboot.img。第三步确认内核和设备树。U-Boot 正常但内核起不来需要看串口日志是从哪一行断掉的。如果日志停在设备树加载阶段先怀疑resource.img和设备树不匹配。OpenHarmony 5.1 的 vendor 分区里包含 HDF 驱动配置如果设备树里的某个外设节点与驱动不匹配会造成内核 panic。这时候把日志完整的最后一屏截图对照内核源码中的drivers/hdf相关代码很容易定位。6.2 烧录成功但显示方向反了设备树和系统属性的联动调试系统跑起来之后另一个高频问题是触摸竖屏改为横屏。OpenHarmony 默认可能以竖屏方式启动但你的应用场景需要横屏显示。这个问题一半在设备树一半在系统属性。设备树里LCD 面板的timing和display-timing参数决定了屏幕初始化方向但更多情况下你不需要大改设备树直接设置系统属性hdc shell param set persist.sys.default.orientation landscape reboot不过要注意触摸屏坐标和显示方向必须同步修改否则会出现“显示横了但触摸还是竖的”这种错位。修改触摸方向通常涉及设备树里触控节点的touchscreen-inverted-x、touchscreen-swap-x-y等属性不同触控 IC 的适配方式不一样。如果你在 RK3568 上调试 ov5695/ov8858 这类摄像头模组也是同样的思路先在设备树里确认 I2C 地址和复位引脚正确再看驱动是否匹配 sensor 的输出格式逐层排查。现阶段 OpenHarmony 5.1 在 RK3568 上的稳定度比早期版本好了不少但外设适配仍然依赖板厂和社区的共同努力。如果你用官方标准版源码编译遇到电容触摸、摄像头、以太网这类外设问题不要急着改内核第一步永远是拉开发板厂商的补丁包看看他们的设备树和内核配置差异。把自己编译的镜像和厂商预编译镜像的resource.img做一次二进制对比往往能快速定位到漏掉的设备树配置。烧录只是 OpenHarmony 开发链条里很靠前的一环但这一环塌了后面所有工作都无从谈起。把上面 6 个步骤跑顺之后你手里的 RK3568 板子才真正属于你。之后不管是改开机动画、调触摸方向还是接 EtherCAT 主站做工业控制都可以在这个基础上放心折腾。