南向环境搭建这件事我前后在四台机器上从头装过每次都能踩出不一样的花样同一份教程A 同学照着做一把过B 同学卡在hb: command not foundC 同学编译到 87% 被系统 kill 掉D 同学烧录工具连设备都认不出来。问题不在于教程写得对不对而在于鸿蒙南向开发这条链路上主机系统、Python 版本、构建脚本、源码分支、工具链、烧录工具、开发板固件这几个环节是强耦合的任何一环版本错位报错都会跑到离真正原因很远的地方去。所以这篇不是又一份从零搭建的步骤复述而是一份问题合集把这条链路上真正高频出现的故障按我到底在搭什么—主机—源码—编译—烧录—调试的顺序摊开每个问题给出现象、根因、验证方法、处理方案重点讲清楚为什么这里会错让你下次遇到陌生报错时知道往哪个方向看。刚接手设备侧开发的同学、从应用层转过来的同学以及被构建脚本折磨过几轮的同学都能直接拿去对照。1. 先搞清楚你搭的是哪一套环境别把三份教程混着做1.1 轻量设备、小型设备、标准设备工具链根本不是同一套这是我认为最容易在第一步就埋雷的地方。南向开发不是一个统一的环境按设备能力至少分成三档轻量级无屏、资源极小、跑 LiteOS 内核那一类、小型带简单外设、资源稍宽裕、标准带屏、跑 Linux 内核、完整的图形和多媒体栈。三档的源码裁剪范围、构建脚本参数、产物格式、烧录方式都不一样。轻量设备通常只编出一个几百 KB 到几 MB 的.bin烧录靠串口加一个厂商提供的小工具几秒钟完事标准设备走全量构建产出一堆分区镜像加一个打包后的烧录包构建时间从二十分钟到一个多小时不等。你要是拿轻量设备的教程去搭标准设备的环境会在为什么我的 out 目录里没有那个文件上浪费一整天。还有一条更隐蔽的岔路芯片厂商 SDK 路线和主干源码路线。前者是厂商把源码裁剪好、配好默认配置、附带一键脚本后者是完整仓库需要自己hb set选产品。这两条路的主机依赖、目录结构、烧录流程都不同。很多人失败的真实原因是环境按 A 教程装源码按 B 教程拉烧录按 C 教程做三份教程分别都没错拼在一起必然崩。目标类型典型产物主机资源门槛主要卡点轻量设备单个.bin磁盘 40GB 起内存 8GB 可跑串口驱动、烧录工具版本、Boot 模式时序小型设备.bin 简单分区磁盘 60GB 起内存 8GB外设配置文件、链接脚本标准设备多分区镜像 打包烧录包磁盘 150GB 起内存 16GB 起全量编译 OOM、签名、分区表我的建议很直接动手之前先在纸上写一行我要做的设备属于哪一档、走 SDK 路线还是主干路线、参考的是哪一份文档写不出来就先别装环境。这一分钟的确认能省掉后面半天的自我怀疑。1.2 版本矩阵比操作步骤致命得多南向环境真正的难点从来不是敲哪些命令而是哪些版本能配在一起。源码的 tag、构建工具hb的版本、Python 解释器版本、编译器的版本、IDE 侧插件的版本这几者之间存在隐式的兼容关系而绝大多数报错信息不会告诉你是版本不匹配。典型现象你在源码根目录敲hb set提示命令不存在或者提示某个模块导入失败或者hb build跑到一半报一个语法错误指向的却是构建脚本本身而不是你的代码。这类报错十有八九是hb装在了另一个 Python 环境里或者hb版本和源码里build目录下的脚本对不上。我的做法是源码固定在一个明确的 tag 上不要用会持续变动的主分支。主分支每天在动你今天装好的环境明天可能就编不过而且这种失败极难复现因为代码已经变了。固定 tag 之后把这个 tag 对应的hb版本、Python 版本、依赖清单全部记在一个文本文件里跟着项目走。提示构建失败时第一件事不是搜报错而是把你当前的版本组合打出来贴在日志最前面。后面无论自己排查还是找人帮忙这份信息价值极高。2. 主机侧一半的报错在你敲第一条命令之前就注定了2.1 系统版本、磁盘、文件系统这三道硬门槛主机系统版本是第一道坎。构建脚本里大量依赖 shell 行为和软件包版本系统太老会出现某些包版本不够、某些语法不支持系统太新又可能出现依赖库 ABI 变化导致的链接失败。实践下来选一个被文档明确支持过的长期支持版本比自己折腾最新的更省时间。磁盘是第二道坎也是最容易被低估的。全量源码加上构建产物再加上交叉编译工具链、ccache 缓存100GB 起步是保守估计留 200GB 才算从容。我见过磁盘写到 95% 之后出现的各种奇怪错误构建中途报无法写入、链接阶段莫名失败、日志文件被截断。更坑的是磁盘满导致的失败往往不会明确提示磁盘已满而是抛一个完全无关的编译错误。养成习惯编译前先df -h看一眼。文件系统是第三道坎而且极其隐蔽。源码必须放在大小写敏感、支持符号链接、支持可执行权限的本地 Linux 文件系统上典型的 ext4。如果你把源码放在 Windows 的 NTFS 分区再挂载过来或者放在 exFAT 的移动硬盘上会遇到符号链接创建失败、文件名大小写冲突导致头文件互相覆盖、脚本没有执行权限、编译产物权限异常。这些问题的报错指向都很迷惑比如某个头文件重复定义其实是因为Foo.h和foo.h被当成同一个文件了。内存也要提前算。经验值是每个编译线程约 2GB 内存-j8大概需要 16GB 可用内存。内存不够时构建进程会被系统直接杀掉现象是编译跑到某个百分比忽然中断日志末尾没有任何错误行。2.2 Python 多版本共存是重灾区南向构建链路上有大量 Python 脚本而主机自带的 Python 版本往往和脚本期望的不一致。一旦你为了别的项目装过 pyenv、conda、虚拟环境之类的东西python3到底指向哪个解释器就变得不确定了。典型症状有这么几类ModuleNotFoundError: No module named xxx但你明明pip install过了——因为装到了另一个解释器脚本第一行报语法错误指向的是看起来很正常的代码——因为用高版本解释器跑了低版本语法的脚本hb命令在 A 终端能用在 B 终端不能——因为 PATH 顺序不同。排查手法很朴素三行命令定位which -a python3 # 看有几个解释器顺序是什么 python3 -V # 当前默认版本 python3 -c import sys; print(sys.executable) # 确认真实路径处理思路有两条要么把系统默认的python3指向构建脚本期望的版本要么在脚本调用时显式指定解释器。我更推荐后者因为它不影响系统其他工具。另外几个纪律性问题不要用sudo pip install往系统环境里装包容易和系统包管理器打架不要把 pip 装到 root 用户的用户目录普通用户跑构建就找不到了安装依赖时把 pip 源换成国内镜像能省掉大量因网络导致的超时失败。一个很实用的小技巧构建脚本报模块缺失时别急着全局安装先确认脚本到底用的是哪个解释器——看它的 shebang 行或者在脚本开头插一行打印sys.executable。很多我明明装了的问题到这一步就明白了。2.3 依赖包不全导致的诡异报错系统依赖包缺失是新手阶段最高频的失败原因因为报错信息通常完全不提缺包。下面这张表是我整理的高频对照遇到时可以直接查报错片段实际缺失的东西处理方向fatal error: openssl/ssl.h: No such file加密库开发头文件安装libssl-devcannot find -lz/zlib.h找不到压缩库开发包安装zlib1g-devi386/ 32 位相关链接失败32 位兼容库安装libc6-dev-i386、lib32z1一类mtools/mkfs.vfat找不到制作文件系统镜像的工具安装mtools、dosfstoolsninja: command not found构建后端安装ninja-build配置阶段报bc或ruby不存在配置生成脚本依赖安装bc、rubyPermission denied跑脚本缺可执行位或文件系统不支持检查挂载参数、补chmod x我的经验是一次性把官方文档给出的依赖清单全部装完不要一条条试错。逐条试错的时间成本远高于多装几个用不上的包。装完之后把那条命令存成一个脚本文件放在家目录下次换机器直接跑。3. 源码同步卡住、中断、目录损坏3.1 同步中断的几种表现与恢复姿势源码是用repo管理的多仓库结构同步阶段最常见的失败是中途断开。表现是某个子仓停在 0% 或者 99%整体命令挂住不动或者报某个仓 fetch 失败。处理上有几个递进的方案。先在命令上加超时和并发控制把并发降下来比如带-j4很多失败是因为并发太高导致单连接超时再不行就针对单个仓单独同步repo sync 仓路径避开整批操作如果.repo目录已经损坏用repo fsck检查一下实在不行把出问题的那个仓目录整体删掉重新同步比反复重试更快。还有一类失败跟磁盘和文件系统有关容易被误判成网络问题。源码里存在大量长路径和符号链接如果源码目录放在某种不支持链接的文件系统上同步阶段就会报创建链接失败。所以前面强调的本地 ext4在这里会第二次咬你。注意同步阶段千万不要在源码目录里做任何清理尤其是别删除.repo下的隐藏目录那里面是版本控制元信息删了等于整仓重来。3.2 首次全量编译之前值得先做的三件事很多人拉完源码直接hb build然后等四十分钟拿到一个失败结果再回过头猜问题。我习惯在第一次全量编译之前先做三件小事成本很低但收益很大。第一件源码根目录执行hb set确认能正确列出可选产品并且能选中。选中后应该生成一个配置文件里面记录了你选的产品和路径。这一步如果报错说明hb本身或 Python 环境有问题和编译无关先解决它。第二件用hb -h、hb build -h看一眼参数说明。重点看全量编译和增量编译的开关、并发控制参数、日志输出参数。很多人不知道有-f这类强制全量的选项导致配置改了没生效还在原地打转。第三件先编译一个最小的目标或者单个组件验证工具链是否可用。全量编译要跑几十分钟才能暴露工具链问题小目标几分钟就能告诉你交叉编译器能不能正常调用。3.3 编译到一半被 killOOM 与并发的取舍全量编译失败里最让人抓狂的一种是没有任何错误信息。日志末尾是ninja: build stopped: subcommand failed或者干脆断在一半往上翻找不到任何error:行。这大概率是内存耗尽进程被系统的内存管理杀掉了。确认方法只有一个去看内核日志dmesg | grep -i killed process如果能看到类似Out of memory: Killed process ... (cc1plus)的记录就板上钉钉了。处理方案按优先级排先把并发降下来从-j8降到-j4甚至-j2代价是时间变长但能编过其次加交换空间给系统一个缓冲区sudo fallocate -l 8G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile free -h # 确认生效交换空间不是万能药它只是让峰值内存有地方溢出编译速度会掉但至少能跑完。长期方案还是加内存条或者把编译任务拆开做增量。另一个常被忽略的点是ccache。做过一次全量成功后打开 ccache第二次编译哪怕改了配置清了 out 目录速度差异非常明显。设置一个足够大的缓存目录把它配置到环境变量里几十 GB 的磁盘换几十分钟的编译时间很划算。4. 编过了不等于跑得起来产物与烧录4.1 out 目录看不懂就会拿错文件构建产物目录结构是有层次的产品名一层、中间对象一层、最终产物一层、打包结果一层。很多人烧录失败的第一原因就是从错误的目录里拿了错误的文件。几个关键区分中间对象文件.o不能烧未签名的裸镜像在需要签名的场景下烧进去也不会跑轻量设备的.bin和标准设备的分区镜像格式完全不同互相之间绝对不能混用。还有分区表文件它决定了镜像被放到存储介质的什么位置分区表和镜像不匹配轻则烧录工具报错重则设备变砖需要重新进 Boot 模式恢复。我自己的习惯是全量编译成功后第一件事不是烧录而是在产物目录里把最终要用的那两三个文件名记下来写进笔记。下次编译完直接按名字去找不去翻目录结构。4.2 串口识别不了、识别了连不上串口是南向开发的生命线日志、烧录、调试全靠它。问题分成两层系统认不认这个设备以及你能不能打开这个设备。先看认不认。在 Linux 下插上板子后执行lsusb看有没有新设备、dmesg | tail看有没有插入日志、ls /dev/ttyUSB*或/dev/ttyACM*看设备节点有没有生成。三样都没有问题在 USB 线或者驱动很多 USB 线是纯充电线没有数据线芯这个坑我踩过不止一次换了三根线才发现是线的问题。再看能不能打开。设备节点存在但打不开报Permission denied是当前用户不在串口设备所属的用户组里。把用户加到对应组之后必须重新登录才生效很多人加完组发现还是不行就是因为没重新登录。还有一类非常隐蔽的冲突串口被别的程序占用了。IDE 的串口监视器开着你再用另一个串口助手去连就会失败或者显示乱码。排查时把其他工具全关掉只留一个。Windows 侧的问题主要是驱动和设备管理器里的黄色感叹号以及某些系统版本对未签名驱动的限制。这时候换一台机器或者换一个已知可用的驱动版本比在原机上死磕快得多。波特率也值得单独说一句。烧录和日志输出用的波特率不一定相同有的方案烧录用一个较高的波特率运行日志用标准的 115200。搞混了的表现是日志全是乱码或者烧录工具一直等握手。乱码第一反应应该是波特率不对而不是板子坏了。4.3 烧录失败的几类现象与定位顺序烧录失败的现象五花八门但归因其实就那么几类按下面的顺序排查效率最高现象优先怀疑验证方法工具提示找不到设备没进 Boot/烧录模式、线材问题按指定时序重新上电、换数据线开始烧录后很快中断供电不足、USB 口供电能力弱换主机后置 USB 口或带供电的集线器烧到中途校验失败镜像与分区表不匹配、存储介质异常核对分区表版本、换一块板子验证烧录成功但设备无输出镜像类型错、签名未通过、波特率错换一个已知可用的镜像做对照反复烧反复失败烧录工具版本与芯片方案不匹配换工具版本优先用 SDK 附带的那个进 Boot 模式这件事值得单独强调。不同板子的进入方式不同有的是按住某个键再上电有的是短接两个测试点有的需要在极短的时间窗口内操作。时序不对工具就永远找不到设备。这一步建议先用官方文档里的方式确认一次成功之后把动作固化下来别每次靠运气。5. 调试通道设备连不上与签名报错5.1 hdc 连不上的排查顺序设备跑起来之后下一步是通过调试通道连上去。连接失败时按这个顺序查基本能覆盖九成情况。先确认工具本身正常hdc -v看版本hdc list targets看设备列表。列表是空的先看物理连接——USB 线是否插在能传数据的口上某些板子有多个 USB 口只有一个支持调试通道。然后看端口占用。调试通道会起一个后台服务进程如果上次异常退出服务可能卡死。用hdc kill -r重启服务再试这一步能解决相当比例的昨天还好今天就连不上。再看设备侧。轻量设备可能根本不支持这套调试通道只能用串口打印标准设备需要设备侧的守护进程正常启动。设备侧没起来主机侧怎么折腾都没用这时候先回到串口看启动日志。最后看权限。和串口一样USB 设备访问在 Linux 下需要相应的权限规则。设备能被lsusb看到但工具访问不了就是这个原因。写一条设备访问规则放到系统规则目录下重新插拔设备生效。5.2 签名配置错误长什么样标准设备的镜像和安装包通常需要签名签名环节的错误信息往往很抽象比如只告诉你校验失败不告诉你哪一步错了。常见的几类签名配置文件里引用的证书路径写错或者文件缺失证书链不完整只有叶子证书没有中间证书密钥对和证书不匹配用 A 私钥配了 B 证书用了发布证书去签调试用途的包或者反过来。这些问题在工具侧的表现都是签名失败但处理方式完全不同。还有一个特别容易被忽略的原因系统时间不同步。证书有有效期主机时间偏差太大比如虚拟机休眠后时间停在几个月前校验就会失败而报错信息完全不会提到时间。我现在的习惯是遇到签名相关的奇怪失败先date看一眼时间。排查顺序上我建议从配置文件开始逐层往下验证配置文件语法对不对很多是缩进或者键名写错、路径解析出来的文件存不存在、证书本身能不能正常读取、证书和密钥是否配对。每一步单独验证比一次性丢给工具去报错快得多。6. 把环境问题变成可复现的问题6.1 环境快照成本最低的保险南向环境的可怕之处不是难而是坏了之后很难回到好的状态。我吃过一次亏为了装一个工具改了系统库版本结果原本能编译的源码全线报错花了整整一天才恢复。从那之后我养成了两个习惯。第一个是记录版本快照。每次环境配通立刻把这几样东西存下来系统版本、内核版本、python3 -V、hb -v、repo --version、源码 tag、交叉编译器版本。存成一个env.txt放在项目目录里。后面任何人包括三个月后的自己复现环境照着这个文件对齐就行。第二个是编译成功后立刻做快照。用虚拟机的直接打快照或者克隆一份物理机的至少把关键配置文件环境变量、设备规则、构建配置打包备份。这个动作花五分钟能省掉未来一整天。6.2 日志留存和一次只改一个变量构建和烧录的日志一定要落盘不要只看终端滚动。命令后面接一个21 | tee build.log把完整输出存下来。终端缓冲区就那么点真正有用的错误往往在滚过去的前几百行。排查方法上我坚持一条铁律一次只改一个变量。同时改 Python 版本又改源码分支又改编译参数编过了你不知道是哪个起了作用编不过你也不知道是哪个搞坏的。慢一点但每一步都算数。6.3 一张随身自查表最后给一张我自己在用的速查表遇到环境崩了的时候从上往下过一遍检查项命令 / 动作期望结果磁盘空间df -h剩余 50GB内存与交换free -h可用内存 ≥ 每线程 2GB源码文件系统df -T 源码目录ext4 或同类本地文件系统Python 解释器which -a python3只有一个且版本符合要求构建工具hb -h正常输出版本和帮助串口设备ls /dev/ttyUSB*有节点且当前用户可读写调试通道hdc list targets能看到设备序列号用下来最大的体会是南向环境搭建真正的门槛不在知不知道命令而在建立一条从现象到根因的推理链。刚上手的时候我总想着找一个能一把过的教程后来发现根本不存在——因为每台机器的既有状态都不一样。反倒是把每个报错当成一个待验证的假设用最小代价去证伪速度会越来越快。现在我遇到没见过的问题第一反应已经不是搜关键词而是先问自己这条链路上上一个被验证正常的环节是哪里从那之后往下走问题基本都藏在不远的地方。这个思路比任何一份清单都管用。
南向环境搭建这件事我前后在四台机器上从头装过每次都能踩出不一样的花样同一份教程A 同学照着做一把过B 同学卡在hb: command not foundC 同学编译到 87% 被系统 kill 掉D 同学烧录工具连设备都认不出来。问题不在于教程写得对不对而在于鸿蒙南向开发这条链路上主机系统、Python 版本、构建脚本、源码分支、工具链、烧录工具、开发板固件这几个环节是强耦合的任何一环版本错位报错都会跑到离真正原因很远的地方去。所以这篇不是又一份从零搭建的步骤复述而是一份问题合集把这条链路上真正高频出现的故障按我到底在搭什么—主机—源码—编译—烧录—调试的顺序摊开每个问题给出现象、根因、验证方法、处理方案重点讲清楚为什么这里会错让你下次遇到陌生报错时知道往哪个方向看。刚接手设备侧开发的同学、从应用层转过来的同学以及被构建脚本折磨过几轮的同学都能直接拿去对照。1. 先搞清楚你搭的是哪一套环境别把三份教程混着做1.1 轻量设备、小型设备、标准设备工具链根本不是同一套这是我认为最容易在第一步就埋雷的地方。南向开发不是一个统一的环境按设备能力至少分成三档轻量级无屏、资源极小、跑 LiteOS 内核那一类、小型带简单外设、资源稍宽裕、标准带屏、跑 Linux 内核、完整的图形和多媒体栈。三档的源码裁剪范围、构建脚本参数、产物格式、烧录方式都不一样。轻量设备通常只编出一个几百 KB 到几 MB 的.bin烧录靠串口加一个厂商提供的小工具几秒钟完事标准设备走全量构建产出一堆分区镜像加一个打包后的烧录包构建时间从二十分钟到一个多小时不等。你要是拿轻量设备的教程去搭标准设备的环境会在为什么我的 out 目录里没有那个文件上浪费一整天。还有一条更隐蔽的岔路芯片厂商 SDK 路线和主干源码路线。前者是厂商把源码裁剪好、配好默认配置、附带一键脚本后者是完整仓库需要自己hb set选产品。这两条路的主机依赖、目录结构、烧录流程都不同。很多人失败的真实原因是环境按 A 教程装源码按 B 教程拉烧录按 C 教程做三份教程分别都没错拼在一起必然崩。目标类型典型产物主机资源门槛主要卡点轻量设备单个.bin磁盘 40GB 起内存 8GB 可跑串口驱动、烧录工具版本、Boot 模式时序小型设备.bin 简单分区磁盘 60GB 起内存 8GB外设配置文件、链接脚本标准设备多分区镜像 打包烧录包磁盘 150GB 起内存 16GB 起全量编译 OOM、签名、分区表我的建议很直接动手之前先在纸上写一行我要做的设备属于哪一档、走 SDK 路线还是主干路线、参考的是哪一份文档写不出来就先别装环境。这一分钟的确认能省掉后面半天的自我怀疑。1.2 版本矩阵比操作步骤致命得多南向环境真正的难点从来不是敲哪些命令而是哪些版本能配在一起。源码的 tag、构建工具hb的版本、Python 解释器版本、编译器的版本、IDE 侧插件的版本这几者之间存在隐式的兼容关系而绝大多数报错信息不会告诉你是版本不匹配。典型现象你在源码根目录敲hb set提示命令不存在或者提示某个模块导入失败或者hb build跑到一半报一个语法错误指向的却是构建脚本本身而不是你的代码。这类报错十有八九是hb装在了另一个 Python 环境里或者hb版本和源码里build目录下的脚本对不上。我的做法是源码固定在一个明确的 tag 上不要用会持续变动的主分支。主分支每天在动你今天装好的环境明天可能就编不过而且这种失败极难复现因为代码已经变了。固定 tag 之后把这个 tag 对应的hb版本、Python 版本、依赖清单全部记在一个文本文件里跟着项目走。提示构建失败时第一件事不是搜报错而是把你当前的版本组合打出来贴在日志最前面。后面无论自己排查还是找人帮忙这份信息价值极高。2. 主机侧一半的报错在你敲第一条命令之前就注定了2.1 系统版本、磁盘、文件系统这三道硬门槛主机系统版本是第一道坎。构建脚本里大量依赖 shell 行为和软件包版本系统太老会出现某些包版本不够、某些语法不支持系统太新又可能出现依赖库 ABI 变化导致的链接失败。实践下来选一个被文档明确支持过的长期支持版本比自己折腾最新的更省时间。磁盘是第二道坎也是最容易被低估的。全量源码加上构建产物再加上交叉编译工具链、ccache 缓存100GB 起步是保守估计留 200GB 才算从容。我见过磁盘写到 95% 之后出现的各种奇怪错误构建中途报无法写入、链接阶段莫名失败、日志文件被截断。更坑的是磁盘满导致的失败往往不会明确提示磁盘已满而是抛一个完全无关的编译错误。养成习惯编译前先df -h看一眼。文件系统是第三道坎而且极其隐蔽。源码必须放在大小写敏感、支持符号链接、支持可执行权限的本地 Linux 文件系统上典型的 ext4。如果你把源码放在 Windows 的 NTFS 分区再挂载过来或者放在 exFAT 的移动硬盘上会遇到符号链接创建失败、文件名大小写冲突导致头文件互相覆盖、脚本没有执行权限、编译产物权限异常。这些问题的报错指向都很迷惑比如某个头文件重复定义其实是因为Foo.h和foo.h被当成同一个文件了。内存也要提前算。经验值是每个编译线程约 2GB 内存-j8大概需要 16GB 可用内存。内存不够时构建进程会被系统直接杀掉现象是编译跑到某个百分比忽然中断日志末尾没有任何错误行。2.2 Python 多版本共存是重灾区南向构建链路上有大量 Python 脚本而主机自带的 Python 版本往往和脚本期望的不一致。一旦你为了别的项目装过 pyenv、conda、虚拟环境之类的东西python3到底指向哪个解释器就变得不确定了。典型症状有这么几类ModuleNotFoundError: No module named xxx但你明明pip install过了——因为装到了另一个解释器脚本第一行报语法错误指向的是看起来很正常的代码——因为用高版本解释器跑了低版本语法的脚本hb命令在 A 终端能用在 B 终端不能——因为 PATH 顺序不同。排查手法很朴素三行命令定位which -a python3 # 看有几个解释器顺序是什么 python3 -V # 当前默认版本 python3 -c import sys; print(sys.executable) # 确认真实路径处理思路有两条要么把系统默认的python3指向构建脚本期望的版本要么在脚本调用时显式指定解释器。我更推荐后者因为它不影响系统其他工具。另外几个纪律性问题不要用sudo pip install往系统环境里装包容易和系统包管理器打架不要把 pip 装到 root 用户的用户目录普通用户跑构建就找不到了安装依赖时把 pip 源换成国内镜像能省掉大量因网络导致的超时失败。一个很实用的小技巧构建脚本报模块缺失时别急着全局安装先确认脚本到底用的是哪个解释器——看它的 shebang 行或者在脚本开头插一行打印sys.executable。很多我明明装了的问题到这一步就明白了。2.3 依赖包不全导致的诡异报错系统依赖包缺失是新手阶段最高频的失败原因因为报错信息通常完全不提缺包。下面这张表是我整理的高频对照遇到时可以直接查报错片段实际缺失的东西处理方向fatal error: openssl/ssl.h: No such file加密库开发头文件安装libssl-devcannot find -lz/zlib.h找不到压缩库开发包安装zlib1g-devi386/ 32 位相关链接失败32 位兼容库安装libc6-dev-i386、lib32z1一类mtools/mkfs.vfat找不到制作文件系统镜像的工具安装mtools、dosfstoolsninja: command not found构建后端安装ninja-build配置阶段报bc或ruby不存在配置生成脚本依赖安装bc、rubyPermission denied跑脚本缺可执行位或文件系统不支持检查挂载参数、补chmod x我的经验是一次性把官方文档给出的依赖清单全部装完不要一条条试错。逐条试错的时间成本远高于多装几个用不上的包。装完之后把那条命令存成一个脚本文件放在家目录下次换机器直接跑。3. 源码同步卡住、中断、目录损坏3.1 同步中断的几种表现与恢复姿势源码是用repo管理的多仓库结构同步阶段最常见的失败是中途断开。表现是某个子仓停在 0% 或者 99%整体命令挂住不动或者报某个仓 fetch 失败。处理上有几个递进的方案。先在命令上加超时和并发控制把并发降下来比如带-j4很多失败是因为并发太高导致单连接超时再不行就针对单个仓单独同步repo sync 仓路径避开整批操作如果.repo目录已经损坏用repo fsck检查一下实在不行把出问题的那个仓目录整体删掉重新同步比反复重试更快。还有一类失败跟磁盘和文件系统有关容易被误判成网络问题。源码里存在大量长路径和符号链接如果源码目录放在某种不支持链接的文件系统上同步阶段就会报创建链接失败。所以前面强调的本地 ext4在这里会第二次咬你。注意同步阶段千万不要在源码目录里做任何清理尤其是别删除.repo下的隐藏目录那里面是版本控制元信息删了等于整仓重来。3.2 首次全量编译之前值得先做的三件事很多人拉完源码直接hb build然后等四十分钟拿到一个失败结果再回过头猜问题。我习惯在第一次全量编译之前先做三件小事成本很低但收益很大。第一件源码根目录执行hb set确认能正确列出可选产品并且能选中。选中后应该生成一个配置文件里面记录了你选的产品和路径。这一步如果报错说明hb本身或 Python 环境有问题和编译无关先解决它。第二件用hb -h、hb build -h看一眼参数说明。重点看全量编译和增量编译的开关、并发控制参数、日志输出参数。很多人不知道有-f这类强制全量的选项导致配置改了没生效还在原地打转。第三件先编译一个最小的目标或者单个组件验证工具链是否可用。全量编译要跑几十分钟才能暴露工具链问题小目标几分钟就能告诉你交叉编译器能不能正常调用。3.3 编译到一半被 killOOM 与并发的取舍全量编译失败里最让人抓狂的一种是没有任何错误信息。日志末尾是ninja: build stopped: subcommand failed或者干脆断在一半往上翻找不到任何error:行。这大概率是内存耗尽进程被系统的内存管理杀掉了。确认方法只有一个去看内核日志dmesg | grep -i killed process如果能看到类似Out of memory: Killed process ... (cc1plus)的记录就板上钉钉了。处理方案按优先级排先把并发降下来从-j8降到-j4甚至-j2代价是时间变长但能编过其次加交换空间给系统一个缓冲区sudo fallocate -l 8G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile free -h # 确认生效交换空间不是万能药它只是让峰值内存有地方溢出编译速度会掉但至少能跑完。长期方案还是加内存条或者把编译任务拆开做增量。另一个常被忽略的点是ccache。做过一次全量成功后打开 ccache第二次编译哪怕改了配置清了 out 目录速度差异非常明显。设置一个足够大的缓存目录把它配置到环境变量里几十 GB 的磁盘换几十分钟的编译时间很划算。4. 编过了不等于跑得起来产物与烧录4.1 out 目录看不懂就会拿错文件构建产物目录结构是有层次的产品名一层、中间对象一层、最终产物一层、打包结果一层。很多人烧录失败的第一原因就是从错误的目录里拿了错误的文件。几个关键区分中间对象文件.o不能烧未签名的裸镜像在需要签名的场景下烧进去也不会跑轻量设备的.bin和标准设备的分区镜像格式完全不同互相之间绝对不能混用。还有分区表文件它决定了镜像被放到存储介质的什么位置分区表和镜像不匹配轻则烧录工具报错重则设备变砖需要重新进 Boot 模式恢复。我自己的习惯是全量编译成功后第一件事不是烧录而是在产物目录里把最终要用的那两三个文件名记下来写进笔记。下次编译完直接按名字去找不去翻目录结构。4.2 串口识别不了、识别了连不上串口是南向开发的生命线日志、烧录、调试全靠它。问题分成两层系统认不认这个设备以及你能不能打开这个设备。先看认不认。在 Linux 下插上板子后执行lsusb看有没有新设备、dmesg | tail看有没有插入日志、ls /dev/ttyUSB*或/dev/ttyACM*看设备节点有没有生成。三样都没有问题在 USB 线或者驱动很多 USB 线是纯充电线没有数据线芯这个坑我踩过不止一次换了三根线才发现是线的问题。再看能不能打开。设备节点存在但打不开报Permission denied是当前用户不在串口设备所属的用户组里。把用户加到对应组之后必须重新登录才生效很多人加完组发现还是不行就是因为没重新登录。还有一类非常隐蔽的冲突串口被别的程序占用了。IDE 的串口监视器开着你再用另一个串口助手去连就会失败或者显示乱码。排查时把其他工具全关掉只留一个。Windows 侧的问题主要是驱动和设备管理器里的黄色感叹号以及某些系统版本对未签名驱动的限制。这时候换一台机器或者换一个已知可用的驱动版本比在原机上死磕快得多。波特率也值得单独说一句。烧录和日志输出用的波特率不一定相同有的方案烧录用一个较高的波特率运行日志用标准的 115200。搞混了的表现是日志全是乱码或者烧录工具一直等握手。乱码第一反应应该是波特率不对而不是板子坏了。4.3 烧录失败的几类现象与定位顺序烧录失败的现象五花八门但归因其实就那么几类按下面的顺序排查效率最高现象优先怀疑验证方法工具提示找不到设备没进 Boot/烧录模式、线材问题按指定时序重新上电、换数据线开始烧录后很快中断供电不足、USB 口供电能力弱换主机后置 USB 口或带供电的集线器烧到中途校验失败镜像与分区表不匹配、存储介质异常核对分区表版本、换一块板子验证烧录成功但设备无输出镜像类型错、签名未通过、波特率错换一个已知可用的镜像做对照反复烧反复失败烧录工具版本与芯片方案不匹配换工具版本优先用 SDK 附带的那个进 Boot 模式这件事值得单独强调。不同板子的进入方式不同有的是按住某个键再上电有的是短接两个测试点有的需要在极短的时间窗口内操作。时序不对工具就永远找不到设备。这一步建议先用官方文档里的方式确认一次成功之后把动作固化下来别每次靠运气。5. 调试通道设备连不上与签名报错5.1 hdc 连不上的排查顺序设备跑起来之后下一步是通过调试通道连上去。连接失败时按这个顺序查基本能覆盖九成情况。先确认工具本身正常hdc -v看版本hdc list targets看设备列表。列表是空的先看物理连接——USB 线是否插在能传数据的口上某些板子有多个 USB 口只有一个支持调试通道。然后看端口占用。调试通道会起一个后台服务进程如果上次异常退出服务可能卡死。用hdc kill -r重启服务再试这一步能解决相当比例的昨天还好今天就连不上。再看设备侧。轻量设备可能根本不支持这套调试通道只能用串口打印标准设备需要设备侧的守护进程正常启动。设备侧没起来主机侧怎么折腾都没用这时候先回到串口看启动日志。最后看权限。和串口一样USB 设备访问在 Linux 下需要相应的权限规则。设备能被lsusb看到但工具访问不了就是这个原因。写一条设备访问规则放到系统规则目录下重新插拔设备生效。5.2 签名配置错误长什么样标准设备的镜像和安装包通常需要签名签名环节的错误信息往往很抽象比如只告诉你校验失败不告诉你哪一步错了。常见的几类签名配置文件里引用的证书路径写错或者文件缺失证书链不完整只有叶子证书没有中间证书密钥对和证书不匹配用 A 私钥配了 B 证书用了发布证书去签调试用途的包或者反过来。这些问题在工具侧的表现都是签名失败但处理方式完全不同。还有一个特别容易被忽略的原因系统时间不同步。证书有有效期主机时间偏差太大比如虚拟机休眠后时间停在几个月前校验就会失败而报错信息完全不会提到时间。我现在的习惯是遇到签名相关的奇怪失败先date看一眼时间。排查顺序上我建议从配置文件开始逐层往下验证配置文件语法对不对很多是缩进或者键名写错、路径解析出来的文件存不存在、证书本身能不能正常读取、证书和密钥是否配对。每一步单独验证比一次性丢给工具去报错快得多。6. 把环境问题变成可复现的问题6.1 环境快照成本最低的保险南向环境的可怕之处不是难而是坏了之后很难回到好的状态。我吃过一次亏为了装一个工具改了系统库版本结果原本能编译的源码全线报错花了整整一天才恢复。从那之后我养成了两个习惯。第一个是记录版本快照。每次环境配通立刻把这几样东西存下来系统版本、内核版本、python3 -V、hb -v、repo --version、源码 tag、交叉编译器版本。存成一个env.txt放在项目目录里。后面任何人包括三个月后的自己复现环境照着这个文件对齐就行。第二个是编译成功后立刻做快照。用虚拟机的直接打快照或者克隆一份物理机的至少把关键配置文件环境变量、设备规则、构建配置打包备份。这个动作花五分钟能省掉未来一整天。6.2 日志留存和一次只改一个变量构建和烧录的日志一定要落盘不要只看终端滚动。命令后面接一个21 | tee build.log把完整输出存下来。终端缓冲区就那么点真正有用的错误往往在滚过去的前几百行。排查方法上我坚持一条铁律一次只改一个变量。同时改 Python 版本又改源码分支又改编译参数编过了你不知道是哪个起了作用编不过你也不知道是哪个搞坏的。慢一点但每一步都算数。6.3 一张随身自查表最后给一张我自己在用的速查表遇到环境崩了的时候从上往下过一遍检查项命令 / 动作期望结果磁盘空间df -h剩余 50GB内存与交换free -h可用内存 ≥ 每线程 2GB源码文件系统df -T 源码目录ext4 或同类本地文件系统Python 解释器which -a python3只有一个且版本符合要求构建工具hb -h正常输出版本和帮助串口设备ls /dev/ttyUSB*有节点且当前用户可读写调试通道hdc list targets能看到设备序列号用下来最大的体会是南向环境搭建真正的门槛不在知不知道命令而在建立一条从现象到根因的推理链。刚上手的时候我总想着找一个能一把过的教程后来发现根本不存在——因为每台机器的既有状态都不一样。反倒是把每个报错当成一个待验证的假设用最小代价去证伪速度会越来越快。现在我遇到没见过的问题第一反应已经不是搜关键词而是先问自己这条链路上上一个被验证正常的环节是哪里从那之后往下走问题基本都藏在不远的地方。这个思路比任何一份清单都管用。
 并测得实打实的加速)
