做开源鸿蒙开发绕不开的第一道门槛就是环境搭建。我拿小熊派nano这块板子从头到尾跑了一遍获取源码、编译源码的完整流程中间踩了不少坑最后整理出一套能直接照着抄的步骤。这篇文章不是贴一堆命令就完事的我会把每一步背后的原因、可能出的问题、排查方法都讲清楚适合第一次接触开源鸿蒙编译环境的新手也适合编译时遇到莫名其妙报错想快速定位的人。1. 开工之前先把环境和路线想清楚1.1 小熊派nano是块什么板子小熊派nanoBearPi-Nano是一块以 Hi3861V100 芯片为核心的物联网开发板主打低成本和低门槛。它的定位非常明确不追求高性能而是让开发者以很小的代价跑通一个真实的物联网设备。板子上带了 LED、按键、无源蜂鸣器接口、OLED 排座等常用外设配合 Type-C 供电拿来做传感器数据采集、家居开关这种轻量级应用非常顺手。在开源鸿蒙生态里小熊派nano属于轻量系统设备跑的是 LiteOS-M 内核资源和标准系统完全不同。这意味着编译方式、产物格式、烧录方法都和手机/平板那种大系统有差异但在入门阶段反而能让你看清楚“源码到固件”的完整链路。现在网上大部分开源鸿蒙入门教程都拿它做示例说明这块板子的适配代码是相对成熟、可复现的。选择开发板一定要清醒小熊派nano不是拿来看炫酷 UI 的它是用来理解系统级别的编译、移植、驱动、烧录这些底层流程的。目标如果是深入嵌入式应用开发用它是非常合适的第一步。1.2 环境搭建的三条主流路线怎么选开源鸿蒙官方文档大多以 Ubuntu 作为开发环境但开发者的实际宿主系统通常是 Windows。这里就有三条常见路线虚拟机、WSL、双系统还有一条辅助路线 Docker。路线优点缺点推荐度虚拟机 Ubuntu与官方文档一致、快照回滚方便、USB/串口透传成熟占用资源、磁盘性能打折扣最推荐WSL2启动快、和 Windows 文件互操作方便早期版本 I/O 慢、USB 串口透传配置复杂可以但要折腾双系统 Linux性能最强、没有虚拟化层干扰安装分区有风险、切换系统麻烦进阶用Docker 容器纯净、可复现、适合 CI设备调试和烧录不方便不推荐入门我自己的选择是虚拟机 Ubuntu 20.04。理由很实际官方文档很多是拿这个环境做验证的你照着命令操作出错的概率最小。虚拟机快照功能特别适合环境搭建这种操作——每次做完一个关键节点就存一个快照后面搞崩了直接回滚不用重新下载几十 GB 源码。硬件配置上建议至少 4 核 CPU、8GB 内存、60GB 可用磁盘。如果机器只有 4GB 内存编译时大概率会被 OOM 干掉后面我会讲到用 swap 缓解的方案。1.3 我推荐的目录规划与系统版本系统方面我建议直接上 Ubuntu 20.04 LTS 64 位。虽然 22.04 也能跑但从实际踩坑经历看22.04 上会遇到更多“版本太新导致库不兼容”的问题比如 libncurses5 装不上、python3 版本过高引发工具链行为差异。20.04 是老牌稳定环境等流程完全跑通之后再迁移到新版本也不迟。源码目录建议统一放在用户主目录下的~/openharmony不要放在/root不要放在中文路径也不要放在 NTFS/FAT 这类跨文件系统挂载点。原因很简单后续编译工具链会创建大量符号链接和中间文件跨文件系统经常出现 ln 失败或权限错乱root 用户生成的产物会让普通用户无法清理中文路径则可能让某些脚本崩溃。另外强烈建议完成基础环境和源码同步后立即给虚拟机做一次快照。源码这个东西重新下载的时间成本极高快照一次等于给自己买了保险。后面就算你把 hb 配置或 vendor 目录改坏了回滚到快照也就几分钟的事。2. 基础环境准备把 Ubuntu 调教到能干活的状态2.1 安装基础软件包新装的 Ubuntu 缺的东西很多先把编译相关的依赖一次性装齐sudo apt update sudo apt upgrade -y sudo apt install -y git curl wget unzip tar sudo apt install -y python3 python3-pip sudo apt install -y build-essential gcc g make sudo apt install -y libncurses5-dev zlib1g-dev flex bison libssl-dev sudo apt install -y gcc-multilib g-multilib这些包各司其职git是源码同步的基础curl/wget用来下载 repo 脚本和工具build-essential提供了最基础的 C/C 编译环境libncurses5-dev供内核/系统层配置菜单使用flex和bison是词法语法分析器很多编译工具链生成代码时会用到multilib系列提供 32 位兼容库交叉编译流程里调用 32 位宿主工具时离不开它。这里有个版本坑Ubuntu 22.04 之后默认软件源里已经没有libncurses5-dev只提供libncurses-dev。遇到Unable to locate package libncurses5-dev时直接用libncurses-dev替代即可大部分场景下不影响。如果还缺个别依赖报错信息会明确提示用sudo apt install补上就行不用怕依赖问题缺哪个补哪个。2.2 配置 Python 和 Git开源鸿蒙的编译脚本和 repo 工具都是 Python 写的所以 Python 环境必须可靠。检查当前版本python3 --version建议 3.8 以上。20.04 自带的是 Python 3.8符合要求。接下来升级 pippython3 -m pip install --upgrade pip setuptools如果提示pip模块不存在先执行sudo apt install -y python3-pip。Git 配置是很多新手会漏掉的一步。repo 在操作一些 git 子命令时需要读取用户名和邮箱不配置的话同步源码时会出现报错或卡住。提前做好git config --global user.name yourname git config --global user.email youexample.com用户名邮箱随便填只要格式合法即可不一定非得是真实信息。另外如果后续同步包含大文件仓库还需要安装 git-lfssudo apt install -y git-lfs git lfs install某些固件、图片、预编译库会以 LFS 方式存储没装这个同步出来的文件会是一个几百字节的指针文件而不是真正的二进制内容编译时就会出现莫名其妙的“文件格式无法识别”错误。2.3 安装并验证 repo 工具repo 不是某个开源鸿蒙特有的工具它是业界常用的一套多仓库管理脚本用 manifest 文件把成百上千个 Git 仓库组织到一起。开源鸿蒙源码仓库数量非常多手动逐个 clone 不现实必须通过 repo 一键同步。安装方式我推荐直接下载 Gitee 码云上的 repo 脚本到用户目录mkdir -p ~/bin curl -s https://gitee.com/openharmony/misc/raw/master/tools/repo ~/bin/repo chmod ax ~/bin/repo echo export PATH$HOME/bin:$PATH ~/.bashrc source ~/.bashrc验证是否装好repo version如果输出类似repo version v2.32后面的信息说明可以用了。如果提示No such file or directory先检查~/bin/repo文件是否存在再检查第一行解释器是python还是python3。这个问题我在下一节详细说。另外不建议用发行版自带的 repoapt install repo版本通常比较旧对源码的 manifest 格式兼容性差我见过很多旧版 repo 在同步时直接报Unsupported manifest format。2.4 一个特别容易踩的坑python 和 python3 混用这个坑几乎所有人都躲不过。你打开~/bin/repo看一眼脚本第一行很可能是#!/usr/bin/env python但 Ubuntu 20.04/22.04 默认只安装了python3没有/usr/bin/python这个文件。执行repo时系统解释器找不到就会报No such file or directory或者更诡异的SyntaxError。解决办法就是把系统缺的python软链到python3sudo apt install -y python-is-python3装完之后验证python --version能正常输出版本号就没问题了。这个软链接不仅影响 repo源码里很多子脚本、编译工具也会用到python命令所以提前处理好能省掉后续一大半 Python 相关的幺蛾子。如果安装后仍报缺什么 Python 模块先看报错里的模块名一般就是requests、setuptools之类的用 pip 装上即可python3 -m pip install requests setuptools3. 获取源码repo init repo sync 的完整流程3.1 版本分支怎么选获取源码之前必须先决定用哪个分支。开源鸿蒙的仓库用分支和 tag 管理版本常见的有这么几类master 主线代码最新功能推进快但变动也快今天能编的代码下周可能因为某个仓的改动就编不了。OpenHarmony-3.0-LTS长期支持版本资源适配较全教程资料最丰富是小熊派nano入门的首选。OpenHarmony-3.1-Release/4.0-Release 等功能更多但板级适配需要自己确认部分流程和 3.0 有差异。我强烈建议新手先锁死 3.0-LTS。小熊派nano的官方适配代码在这个分支上是完整的网上绝大多数教程也基于它遇到问题能对照参考。用 master 或 4.x 也不是不行但那是已经有经验、能自己排查时才做的事。版本选择直接决定后面的编译命令和产物内容一步选错就多浪费好几个小时。分支选择可以参考这个表分支适合人群稳定程度小熊派nano适配master想追新特性、做社区贡献低需确认OpenHarmony-3.0-LTS新手入门、复现教程高官方完整OpenHarmony-4.0-Release想体验新 API中需手动确认3.2 初始化仓库与同步代码确定分支之后开始正式拉取源码。先建目录并进入mkdir -p ~/openharmony cd ~/openharmony repo init -u https://gitee.com/openharmony/manifest.git -b OpenHarmony-3.0-LTS这个过程很快它不下载源码本体只是从 manifest 仓库读取一份配置文件——这份文件告诉 repo项目有哪些子仓库、每个仓库的路径、远程地址、当前该 checkout 哪个 commit。执行成功后目录下会出现.repo隐藏目录里面是后续同步的元数据和 remote 配置这个目录不能删也不要去手工改动它。真正的下载动作是repo syncrepo sync -c -j4-c表示只同步当前分支的代码大幅减少数据量-j4表示并发 4 个仓库同时拉取。初次下载用时取决于网络环境正常在十几分钟到一小时之间。如果家里网络不好可以降到-j2慢一点但失败率明显下降。同步中途断网也是常事不用慌再次执行同一条命令repo 会接着上次的进度继续下载而不是从零开始。如果发现命令卡在某个仓库好久不动可以 CtrlC 后重试一般不会有严重的残留问题。3.3 同步完成后要做什么检查同步完成不等于万事大吉先花两分钟检查ls ~/openharmony repo info | head -30 du -sh ~/openharmony顶层目录应该能看到build、device、kernel、vendor、third_party、foundation、applications等核心目录。如果某个目录缺失或者明显过小说明同步时有仓库没拉完整需要再跑一次repo sync -c -j4。repo info会打印所有仓库的状态可以顺便看有几行error或uninitialized有异常就先补拉。du -sh只是让你对体积有个数轻量系统源码加仓库元数据通常 20G 左右过小说明中途失败了。如果仓库配置了 LFS 大文件还需要执行repo forall -c git lfs pull确保二进制大文件已经真正落盘。这一步不做后面编译到链接固件时经常会报“文件太短”或者invalid ELF header非常坑。3.4 小熊派nano板级代码的补充获取这一步取决于你用的分支。在 3.0-LTS 里小熊派nano的板级适配通常已经随源码带下来了验证方法很简单ls ~/openharmony/vendor/bearpi/bearpi_hm_nano ls ~/openharmony/device/bearpi/bearpi_hm_nano两个目录下能看到config.json、build.gni、hals之类的文件说明适配代码齐全。如果目录为空或不存在说明当前分支没有内置小熊派nano适配需要从社区仓库手动补充。具体地址以该分支官方文档为准大体是cd ~/openharmony/vendor git clone bearpi_nano仓库地址 bearpi/bearpi_hm_nano cd ~/openharmony/device git clone bearpi_nano仓库地址 bearpi/bearpi_hm_nano注意两个目录放的内容不同vendor 下是产品级配置、裁剪方案和编译脚本device 下是芯片相关的驱动和 BSP。缺了任何一个后续hb set都看不到小熊派nano这个产品选项或者编译到一半报设备相关文件找不到。还有一种情况是仓库里自带了构建脚本会在编译时自动从固定地址拉取 SDK那样你就不用手动操作但要保证网络能正常访问那个地址。我见过多人因为只 clone 了主仓没处理 SDK导致编译时中断现象和缺文件一模一样。3.5 网络中断和速度慢的应对写到这里必须说实话源码同步是最容易让人心态爆炸的一步问题几乎都是网络引起的。我的经验是先别急着用高并发新手从-j4开始跑通了再尝试-j8。并发太高只会让每个请求都在排队反而容易触发超时。如果某个仓库反复fatal: unable to access可以单独进入对应目录手动git fetch看看网络是否畅通但更省事的办法是直接重试repo sync -c -j2错峰执行例如放在后半夜。Gitee 码云的服务质量整体靠谱大部分超时是本地网络波动导致的短期问题多试几次往往就过去了。另外提醒一句不要在.repo目录里手动删文件来“修复”repo 的状态记录和 manifest 是配套的手动删了可能引发后续所有仓库重同步。真到了不可恢复的地步宁可把~/openharmony删掉重新下载也别在那手工瞎改。4. 编译环境搭建hb 工具链安装与配置4.1 hb 工具是什么为什么要单独装源码准备好之后还需要一个命令行工具来驱动编译它就是 hbOpenHarmony build。通俗理解hb 是开源鸿蒙的“编译管家”它读取你选定的产品配置调用底层 gn/ninja 工具链批量编译所有模块最后把镜像和固件整合出来。你不需要手动一个个模块去 make只要告诉 hb“编哪个产品”。为什么需要单独安装因为 hb 不在系统软件源里也不是预编译的二进制它就藏在源码build/lite目录下本质是一个 Python 包。官方设计是让你在获取源码后用setup.py把 hb 装到当前用户环境里。这也是新手最容易困惑的地方——总以为编译工具链是 apt 装的其实一半是源码自带一半是本地安装。旧版源码比如 1.x用的是python build.py -p bearpi_hm_nano这种方式直接跑脚本。从 3.0 开始流程统一到了 hb所以网上教程新旧混杂很容易让人懵。先看源码里有没有build/lite/setup.py有就该用 hb 流程。4.2 安装 hb 工具的完整步骤安装前先确认 setuptools 可用sudo apt install -y python3-setuptools然后进入build/lite目录执行安装命令cd ~/openharmony/build/lite python3 setup.py install --user这里的--user参数很关键只安装到当前用户目录不需要 root也不污染系统 Python 环境。即使你只有一个开发用户也建议用这种方式后续升级或者卸载都干净很多。安装完成后hb 的可执行文件会放在$HOME/.local/bin需要手动加入 PATHexport PATH$HOME/.local/bin:$PATH echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc验证是否成功hb help能看到帮助信息就说明安装完成。如果提示ModuleNotFoundError: No module named hb先检查是否在build/lite目录下执行的 setup.py再确认安装过程没有报错最后用python3 -m pip list | grep hb看看包是否真的装上。很多时候只是 PATH 没配置hb 其实已经装在系统里了。4.3 配置环境变量并验证hb 安装好之后正式编译前先要认识源码根目录。进入源码根目录执行cd ~/openharmony hb set这是交互式命令会列出所有已发现的开发板产品。选择列表里的bearpi_hm_nano即可。如果不想用交互菜单也可以直接指定hb set -root ~/openharmony hb set -p bearpi_hm_nano-root把当前源码目录设为根目录-p直接把产品设为小熊派nano。执行完可以用hb env查看当前编译环境hb env输出里应该有 root、product、device_path、kernel 等信息。重点看 product 是不是bearpi_hm_nano再看 device_path 是否指向device/bearpi/bearpi_hm_nano。如果这里显示的 device_path 是空的说明板级适配代码没有识别到回到 3.4 节检查 vendor/device 目录。此时应该养成一个习惯把 PATH 和 root 相关配置写进.bashrc不要每次开终端重敲。我见过太多人编译前忘了source ~/.bashrc然后 hb 一直 not found其实不是环境坏了只是新终端没加载配置。4.4 编译依赖确认 gn、ninja 和工具链在不在hb 只是调度器真正干活的是 gn、ninja、编译器。这些一般在源码自带的prebuilts目录里。检查ls ~/openharmony/prebuilts正常能看到很多工具链目录。如果这个目录不存在或者内容是空的大概率是同步不完整或者你手动删过文件。工具链缺失的症状很典型编译一开始就报ninja: command not found或gn: No such file or directory。这时不要自己去 apt 装 gn/ninja版本对不上反而更乱正确做法是检查源码仓库完整性重新同步对应仓库。编译器方面开源鸿蒙的交叉编译工具链也放在 prebuilts不依赖系统 gcc。但编译某些宿主工具时还会用到系统的 gcc/g所以第 2 章里的依赖包仍然要装。5. 编译源码从 hb build 到拿到烧录固件5.1 第一次编译前必须检查的项真正按下编译按钮前花 5 分钟逐项检查能避免一大半莫名其妙的失败磁盘空间df -h /home至少预留 10GB。编译产物在out目录轻量系统全量编译后也有好几个 GB。源码属主ls -ld ~/openharmony确保目录所有者是当前用户。如果之前用 sudo 创建或修改过某些文件后续编译会因权限不一致报错。修复命令sudo chown -R $USER:$USER ~/openharmony。Python 软链接python --version必须能正常输出如果 no such file 就去装 python-is-python3。hb 可用性which hb能打印路径才行。内存余量free -h。如果内存只有 4G 左右非常建议先加 swap。快速加 swap 的方法sudo fallocate -l 8G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile加完 swap 能显著降低编译中途被 OOM Kill 的概率。注意/swapfile的路径和权限是硬要求权限不对内核会拒绝使用。5.2 执行编译与日志阅读确认无误后执行全量编译cd ~/openharmony hb build -f 21 | tee build.log-f表示强制全量编译。第一次编译必须全量因为 out 目录里什么都没有。编译过程会大量刷日志这时不要干等学会看日志关注最后的输出是否有build success字样。出错时搜索error:或Error:直接定位到第一个错误通常真正的错误在第一个后面一连串都是连锁反应。日志落盘到build.log后可以用grep -i error build.log | head -30快速梳理。编译时长方面四核八线程的虚拟机第一次全量大约 15 到 30 分钟取决于磁盘性能和 CPU。如果中途 Killed先加 swap 再重跑如果中途某个模块报错把报错信息连同 hb 版本一起搜索基本都有答案。编译成功后再次编译时直接用hb build不带 -f走增量编译ninja 只重编改动过的模块通常几秒到几十秒就结束了。5.3 编译产物在哪里怎么确认成功编译完成后小熊派nano的固件产物一般在ls -lh ~/openharmony/out/bearpi_hm_nano/BearPi-HM_Nano/这个目录下会出现几个关键文件Hi3861_wifiiot_app_allinone.bin可以直接烧录的全量固件这是你最需要的东西。Hi3861_wifiiot_app.elf带符号的调试文件调试崩溃问题时用。Hi3861_wifiiot_app.map内存布局图分析内存占用时看它。判断编译是否成功除了看日志里的build success还要看 bin 文件的大小和时间戳。文件时间应该是最新时刻大小正常在几百 KB 到 1MB 级别。如果看到 0 字节或者时间戳是几天前的说明这次编译实际没写出新固件。拿到 bin 之后就可以连接串口烧录到板子了。具体烧录流程不是本文重点我只提两个关键点一是烧录前通常需要让开发板进入下载模式多数做法是按住 BOOT 键再上电二是串口驱动和波特率设置要按官方文档来不同板子的 boot 逻辑有细微差别。5.4 常见编译错误与解决速查表把我在实际过程中遇到以及帮别人排查过的典型问题整理成一张表方便对照报错/现象大概率原因解决办法hb: command not foundhb 未安装或 PATH 未加载重新执行python3 setup.py install --user并把$HOME/.local/bin写进~/.bashrcNo module named hbsetup.py 没装成功确保在build/lite下安装先升级 pip 和 setuptools 再重试No product found板级适配代码缺失或产品名写错检查vendor/bearpi/bearpi_hm_nano和device/bearpi/bearpi_hm_nano确认名字大小写python: No such file or directory系统缺少python软链接sudo apt install -y python-is-python3编译中途 Killed内存不足增加 swap、关闭 GUI、暂时降低并行任务磁盘写满out 目录或源码太大df -h找空间清理旧 out扩展虚拟磁盘invalid ELF header/ 文件太短LFS 大文件未拉取repo forall -c git lfs pullninja/gn not foundprebuilts 不完整重新同步源码不要用 apt 安装替代权限错误导致编译失败源码树被 root 所有sudo chown -R $USER:$USER ~/openharmony这张表不敢说覆盖所有问题但覆盖了新手 90% 的场景。遇到没见过的错误先看第一个 error 出现的位置不要被后面几十行刷屏吓住很多时候错误原因就藏在前三行。6. 编译之后的收尾工作与经验总结6.1 完整流程为什么要从头到尾做一遍环境搭建这件事表面上是在配置工具实际上是在建立“源码管理 构建系统 板级适配”三者关系的全局观。只复制命令不思考换个分支、换个板子就又不会了。我强烈建议新手至少手动完整跑一遍不要用任何一键脚本把每一句命令的作用在笔记里写下来。我第一次跑通整个流程的最大感受是问题基本都出在“环境依赖”而不是“代码逻辑”上。源码本身绝大多数情况是没问题的编译不过大多是 Python 软链接缺失、vendor 目录没放对、磁盘空间不够这类小事。把这些前置条件理顺了后面写业务代码才有意义。另外建议把常用的编译命令整理成一个可复用的脚本比如build.sh内容大致如下#!/bin/bash source ~/.bashrc cd ~/openharmony || exit 1 hb build -f 21 | tee build.log放在源码目录外省得每次敲长命令。脚本第一行必须先 source 环境否则 PATH 可能没加载 hb。6.2 新手最容易忽略的3个细节第一个细节是权限。很多教程会顺手写sudo比如sudo repo sync、sudo python3 setup.py一旦源码树某些文件变成 root 所有后续当前用户编译就会碰到各种 Permission denied。我的原则是除了apt install需要 sudo源码目录内的一切操作都用普通用户已经出问题的用 chown 一次性修复。第二个细节是新终端的环境变量。hb 配置写入.bashrc之后所有新开的终端都会自动生效但如果你用了终端里的“标签页复制”或某些特殊 shell可能没有执行完整 profile这时手动source ~/.bashrc即可。不要一看到 not found 就急着重装 hb先 which 一下看路径。第三个细节是增量编译与全量编译的分工。日常只改了应用或驱动代码用hb build增量就行如果修改了产品级配置、vendor 目录结构、内核裁剪选项再用hb build -f全量重新来。盲目全量不仅浪费时间还会掩盖真正的问题因为日志太多了。6.3 最后分享一个小技巧我现在的做法是在主目录下维护一个env.sh集中管理所有开发环境变量export PATH$HOME/bin:$HOME/.local/bin:$PATH export OHOS_SOURCE_ROOT~/openharmony每次进入新终端先source ~/env.sh不管切到哪个项目都能快速定位。配合alias hbbcd $OHOS_SOURCE_ROOT hb build -f这样的别名操作效率会高很多。这个小习惯算不上什么高深技术但对长期做嵌入式开发的人来说能省下大量重复劳动。看完整套流程你就会发现小熊派nano的环境搭建并不复杂难的是那些零散的、文档里不会细讲的系统细节。把路径、权限、版本差异、命令工具这几件事先理顺后面编译源码的过程其实是很顺利的。希望你也能顺利跑通在“拿到固件”的那一刻前面所有的折腾都值了。