BQ3588C开发板编译踩坑实录：环境配置与常见错误解决

BQ3588C开发板编译踩坑实录：环境配置与常见错误解决

在尝试为国产高性能开发板构建开源鸿蒙系统时，你有没有经历过那种“明明照着文档一步步来，却处处报错”的无力感？尤其是在面对一个尚处于生态建设初期的操作系统——比如 OpenHarmony 时，这种体验几乎是每位开发者必经的“洗礼”。

本文记录的是我在使用贝启科技 BQ3588C 开发板编译 OpenHarmony 源码过程中真实踩过的每一个坑。从权限问题到依赖缺失，再到图形库和内核头文件的隐性绑定，整个过程耗时超过七小时，期间多次重启、清理、重装工具链。如果你也正准备踏上这条路，不妨把这篇文章当作一份“生存指南”。

环境准备不是可选项，而是成败关键

很多新手会误以为：“只要拉下代码，运行 build 脚本就能出镜像。”但现实远比想象复杂。OpenHarmony 的构建流程涉及多个外部工具链、语言运行时、系统级开发库以及网络资源下载，任何一个环节断裂都会导致失败。

我们使用的环境是：
- OS：Ubuntu 22.04 LTS
- 内存：32GB（建议至少16GB）
- 存储空间：预留 100GB SSD 空间
- 源码分支：OpenHarmony 主线（基于 rk3588 平台适配）

⚠️ 特别提醒：不要在虚拟机中使用过低资源配置进行编译，尤其是内存低于16GB或磁盘I/O性能差的情况下，极易出现ccache卡死、链接器超时、进程被 OOM Killer 终止等问题。

第一步：预下载工具链 —— 权限陷阱最先爆发

进入源码根目录后，官方文档提示执行：

build/prebuilts_download.sh

结果刚起步就报错：

PermissionError: [Errno 13] Permission denied: '/home/ph/../openharmony_prebuilts'

原来这个脚本默认试图在用户主目录同级创建名为openharmony_prebuilts的全局缓存目录，而普通用户对此路径无写权限。

尝试用sudo提权运行：

sudo bash build/prebuilts_download.sh

这次终于看到进度条刷起来：

[02:02:49] Requesting https://repo.huaweicloud.com/openharmony/compiler/cmake/3.16.5/linux/cmake-linux-x86-3.16.5.tar.gz ... cmake-linux-x86-3.16.5.tar.gz ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100.0% • 39.9/39.9 MB • 6.6 MB/s • 0:00:00 ... prebuilts_download end

所有工具链（包括 GN、Ninja、Clang、GCC-Linaro、Rust 工具集等）全部下载完成，并解压至/home/ph/prebuilts目录。

💡关键洞察：
虽然以sudo运行存在安全风险，但在当前 OpenHarmony 构建体系中，prebuilts_download.sh并未提供可配置安装路径的参数，且对临时目录有强写入需求。因此，在非 root 用户环境下，必须提权才能顺利完成初始化。

更理想的方案应该是通过环境变量指定PREBUILTS_DIR，但目前该功能尚未开放，只能被动接受这一设计缺陷。

正式编译启动：./build.sh接连暴雷

接下来执行正式构建命令：

./build.sh --product-name dayu210 --ccache

不出所料，第一轮失败：

ohcommandline-tools-linux.zip: Permission denied unzip: cannot find or open ohcommandline-tools-linux.zip ./build.sh: line 121: /home/ph/OpenHarmony_Source/prebuilts/build-tools/common/oh-command-line-tools/ohpm/bin/init: No such file or directory [OHOS ERROR] javac: command not found

短短几行输出暴露了三个独立问题，它们层层嵌套，容易让人误判因果关系。

🔧 问题一：Java 环境缺失 ——javac: command not found

OpenHarmony 使用 Java 编写的打包工具haptobin.sh来处理 HAP 应用包，该脚本内部调用了javac编译辅助类。

解决方案很简单：

sudo apt install openjdk-11-jdk

验证是否生效：

$ javac --version javac 11.0.21

注意必须是 JDK 而非 JRE，且版本需匹配 OpenHarmony 官方推荐的JDK 11。高版本（如 JDK 17）可能导致字节码不兼容。

🔧 问题二：ohpm 初始化失败 ——Permission denied下载中断

另一个关键问题是oh-command-line-tools的自动下载失败。日志显示：

download oh-command-line-tools ohcommandline-tools-linux.zip: Permission denied

这其实是由于脚本尝试将 zip 包写入当前目录，但当前工作区权限受限所致。即使你是项目拥有者，某些挂载分区或 NFS 路径也可能限制写操作。

再次使用sudo执行构建脚本后，下载恢复正常：

sudo ./build.sh --product-name dayu210 --ccache

输出中可以看到：

--2024-01-02 08:45:26-- https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/.../ohcommandline-tools-linux-2.0.0.1.zip Length: 17870081 (17M) [application/zip] Saving to: ‘ohcommandline-tools-linux.zip’ Archive: ohcommandline-tools-linux.zip inflating: oh-command-line-tools/sdkmanager/bin/ohsdkmgr ...

ohpm成功初始化并开始管理 SDK 和模块依赖。

📌经验总结：
ohpm是 OpenHarmony 的包管理器，类似于 npm 或 pip，但它在首次运行时需要动态下载运行时环境。如果不在可信上下文中执行，很容易因权限、网络或路径问题失败。建议提前手动确认其目标路径可写。

🔧 问题三：X11 图形头文件缺失 —— 隐藏依赖的典型代表

继续编译后出现以下致命错误：

../../third_party/flutter/glfw/src/x11_platform.h:39:10: fatal error: 'X11/Xcursor/Xcursor.h' file not found #include <X11/Xcursor/Xcursor.h> ^~~~~~~~~~~~~~~~~~~~~~~ 1 error generated.

这是最典型的“你以为不需要 GUI 就不用装图形库”的反例。尽管你在编译的是嵌入式系统镜像，但构建过程中使用的 Flutter 引擎依赖 GLFW，而后者又依赖 X11 的各种扩展头文件。

解决方法是安装完整的 X.Org 开发套件：

sudo apt install libxt-dev libx11-dev xorg-dev

其中：
-libx11-dev提供基础 X11 协议接口
-libxt-dev支持 Xt Toolkit（老式 GUI 框架）
-xorg-dev是元包，会自动拉取xcursor,xrender,xi等子组件

验证头文件是否存在：

ls /usr/include/X11/Xcursor/Xcursor.h

一旦发现这类头文件缺失，不要只盯着报错的那一行去搜索单个.h文件，而是应安装整套开发包，避免后续反复触发类似问题。

🔧 问题四：OpenSSL 头文件找不到 —— 内核构建阶段的意外依赖

更令人意外的是，在内核编译阶段竟然也出现了依赖问题：

scripts/extract-cert.c:21:10: fatal error: openssl/bio.h: No such file or directory #include <openssl/bio.h> ^~~~~~~~~~~~~~~ compilation terminated. make[2]: *** [scripts/Makefile.host:95: scripts/extract-cert] Error 1

原来 Linux 内核构建脚本extract-cert在生成证书时需要用到 OpenSSL 的 BIO 模块进行 PEM 解析。这是一个常被忽略的构建依赖。

修复方式：

sudo apt install libssl-dev

该包不仅提供头文件，还包括静态库和 pkg-config 配置，确保编译器能正确识别-lssl和-lcrypto。

最终成功编译：一场持久战的胜利

在逐一解决上述问题后，执行完整清理与重建流程：

# 清理旧输出防止冲突 sudo rm -rf out/ hb clean --all # 重新预下载（避免断点续传异常） sudo bash build/prebuilts_download.sh # 开始最终编译 sudo ./build.sh --product-name dayu210 --ccache

经过约7 小时的持续编译（AMD Ryzen 9 5900X + 32GB RAM），终于迎来曙光：

[OHOS INFO] [62292/62293] STAMP out/rk3588/obj/build_configs/kernel_config.stamp [OHOS INFO] [62293/62293] STAMP out/rk3588/obj/build_configs/partition_size_config.stamp [OHOS INFO] ---------------------------------------- [OHOS INFO] build success [OHOS INFO] ----------------------------------------

🎉 成功！生成的系统镜像位于：

out/rk3588/packages/phone/images/

关键镜像文件包括：
-kernel.img：Linux 内核镜像
-ramdisk.img：初始根文件系统
-system.img：主系统分区
-userdata.img：用户数据区

这些镜像可通过 Rockchip 官方烧录工具RKDevTool刷入 BQ3588C 开发板，实现启动测试。

常见问题速查表：一图看清所有坑

实践建议：如何避免重复踩坑

✅ 一次性安装全部构建依赖

与其边编译边补包，不如一开始就装全常用依赖。推荐命令如下：

sudo apt update sudo apt install -y \ git-core gnupg flex bison gperf build-essential \ zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 \ lib32ncurses5-dev x11proto-core-dev libx11-dev libreadline-dev \ libgl1-mesa-dev libglu1-mesa-dev mingw32 uuid-dev libffi-dev \ python3-dev libssl-dev openjdk-11-jdk \ libxt-dev xorg-dev

这套组合覆盖了 C/C++ 编译、跨平台支持、Python 脚本、Java 工具、图形库和安全库等几乎所有可能用到的组件。

✅ 合理使用ccache加速二次构建

添加--ccache参数可以显著提升后续编译速度。首次构建虽无加速效果，但之后修改少量代码时可节省数小时时间。

确保ccache已安装并配置合理缓存大小：

sudo apt install ccache ccache -M 10G # 设置最大缓存为10GB

✅ 使用国内镜像源提升下载稳定性

原始脚本中的下载地址多指向华为云或 DBank CDN，国外网络可能不稳定。可在公司内网部署代理或使用中科大、清华等镜像站替代（需谨慎修改脚本逻辑）。

❌ 不要迷信“无需 sudo”原则

尽管社区普遍强调避免使用sudo执行构建脚本，但在 OpenHarmony 当前构建体系下，ohpm、prebuilts_download.sh等工具的设计并未充分考虑非特权用户的场景。强行降权只会导致更多难以调试的问题。

正确的做法是：在干净的容器或 VM 中以sudo完成构建，完成后立即切换回普通用户操作，降低长期提权带来的风险。

结语：每一次踩坑都是深入理解系统的契机

BQ3588C 作为一款基于 RK3588 的高性能国产开发板，承载着推动 OpenHarmony 在高端设备落地的使命。然而，其构建过程之繁琐，反映出当前国产操作系统生态仍处于“可用”向“易用”过渡的关键阶段。

每一个看似无关紧要的.h文件缺失，背后都可能是跨团队协作、工具链耦合、文档断层的结果。而正是在这种不断排查、验证、修正的过程中，开发者才能真正掌握系统的底层脉络。

希望这份实录能帮你绕开那些我已经趟过的泥潭，把精力集中在更有价值的功能开发上。下一章，我们将进入实际烧录环节，看看如何让这块板子真正“亮”起来。