1. 开篇：从零开始，与HarmonyOS的第一次亲密接触

作为一名在嵌入式领域摸爬滚打了十多年的老工程师，我见证了从8位机到32位MCU，再到如今各种RTOS和轻量级操作系统的演进。当华为推出HarmonyOS，并面向IoT领域开放时，我意识到这不仅仅是又一个操作系统，它背后承载的“一次开发，多端部署”理念，对于解决当前碎片化严重的物联网开发生态，可能是一剂良药。但理念再好，也需要一个落脚点。对于广大开发者，特别是学生和嵌入式爱好者而言，如何低成本、低门槛地迈出HarmonyOS开发的第一步，是大家最关心的问题。

小熊派推出的BearPi-HM_Nano开发板，正是这样一个绝佳的“敲门砖”。它基于海思Hi3861V100这颗Wi-Fi SoC，价格亲民，资源够用，官方配套资料也相对齐全。然而，官方文档往往侧重于步骤罗列，对于环境搭建中可能遇到的“坑”以及背后的原理着墨不多。很多新手朋友照着文档操作，常常在某个环节卡住，耗费大量时间排查，挫败感很强。今天，我就以一名一线开发者的视角，结合我实际搭建环境的全过程，为你拆解BearPi-HM_Nano开发环境搭建的每一个细节。我会告诉你每一步在做什么，为什么这么做，以及我踩过哪些坑、总结出哪些技巧。我们的目标很明确：让你能一次成功，把开发板跑起来，为后续真正的应用开发扫清障碍。

2. 开发环境全景解析：为什么是“Linux服务器+Windows工作台”？

在开始动手之前，我们必须先理解HarmonyOS（特别是针对Hi3861这类轻量级设备）的典型开发模式。它并非像在Windows上开发STM32程序那样，所有工作都在一台电脑上完成。官方推荐的是 “Linux编译服务器 + Windows工作台” 的分布式开发模式。这个架构选择背后有深刻的工程考量，理解它有助于我们后续排查问题。

2.1 核心架构拆解：各司其职，效率至上

这种架构将编译构建这类消耗大量计算资源、对操作系统环境有特定要求的工作，与代码编写、调试、烧录等人机交互频繁的工作分离开来。

1. Linux编译服务器：构建引擎

   • 角色 ：它是整个开发流程的“动力车间”。HarmonyOS的编译构建系统（基于Gn和Ninja）以及针对RISC-V架构的交叉编译工具链（gcc_riscv32），在Linux环境下拥有最好的兼容性和性能。
   • 为什么是Linux？ 首先，很多开源构建工具和链工具原生就是为Linux/Unix环境设计的，在Windows上通过Cygwin或WSL模拟总会遇到一些边界问题。其次，服务器通常拥有更强的CPU和更大的内存，可以显著缩短大型项目的编译时间。最后，统一的Linux环境便于团队协作和持续集成（CI）。
   • 硬件要求 ：一台独立的电脑（可以是旧笔记本、台式机，甚至是树莓派），或者一台云服务器（如阿里云、腾讯云的ECS）。对于个人学习，在Windows上使用虚拟机（如VMware Workstation或VirtualBox）安装Ubuntu也是一个非常普遍且可行的方案。

2. Windows工作台：交互中心

   • 角色 ：它是开发者的“主控台”。我们在这里使用VS Code编写和阅读代码，通过MobaXterm等终端工具远程连接并控制Linux服务器，通过串口工具与开发板通信，以及运行Windows下的烧录工具。
   • 为什么是Windows？ 纯粹出于习惯和工具生态。大多数工程师更熟悉Windows下的图形化操作，VS Code等编辑器的体验也更好。这个工作台本质上是一个强大的客户端。

3. BearPi-HM_Nano开发板：目标设备

   • 角色 ：最终代码运行的硬件平台，也是我们所有工作的价值体现。
   • 连接关系 ：开发板通过USB Type-C线连接到Windows工作台。这根线同时承担了两个重要职责：一是为开发板供电，二是通过板载的CH340芯片转换为串口，实现工作台与开发板的调试信息交互和程序烧录。

我的经验之谈 ：对于个人学习者，我强烈推荐使用 “Windows主机 + VMware Ubuntu虚拟机” 的方案。它兼顾了便利性和性能。将虚拟机设置为“桥接模式”，这样Ubuntu虚拟机就会获得一个与Windows主机同网段的独立IP地址，Windows工作台可以像访问一台真实服务器一样访问它。务必为虚拟机分配足够的资源（建议至少2核CPU、4GB内存、40GB硬盘），否则编译过程会非常缓慢。

2.2 软件工具链选型背后的逻辑

官方文档给出了工具列表，但为什么要装这些？它们之间是如何协作的？了解这个流水线，能让你在出问题时快速定位。

• 代码编辑 (VS Code) ：这只是个编辑器，你可以用任何你喜欢的，但VS Code的远程开发插件（连接Linux服务器）和C/C++插件体验非常好。
• 远程连接与终端 (MobaXterm/PuTTY) ：MobaXterm是我的首选，因为它集成了SSH客户端、SFTP文件传输、串口终端于一身，一个工具搞定所有连接需求，比分开使用PuTTY和WinSCP方便得多。
• 构建系统核心 (Gn + Ninja + SCons + Python) ：
  • Gn (Generate Ninja) ：这是一个元构建系统，它的作用是读取项目中的 BUILD.gn 等配置文件，生成高效的 build.ninja 文件。你可以把它理解为一个高级的、描述构建规则的语言。
  • Ninja ：这是一个专注于速度的小型构建系统。它直接执行 build.ninja 文件中描述的具体编译、链接命令。Gn+Ninja的组合，是Chromium项目带来的先进构建理念，比传统的Makefile在大型项目上构建更快。
  • SCons ：在HarmonyOS的构建流程中，SCons似乎用于一些更上层的构建任务驱动或历史遗留模块。我们需要安装它以确保兼容性。
  • Python 3.7+ ：以上很多工具（如Gn的脚本、一些构建脚本）都是Python编写的，因此它是基础依赖。
• 交叉编译工具链 (gcc_riscv32) ：我们的开发板（Hi3861）的CPU核心是RISC-V架构。我们Windows/Mac的电脑通常是x86架构。 交叉编译 就是指在A架构的机器上，编译生成能在B架构的机器上运行的代码。 gcc_riscv32 就是专门为32位RISC-V架构生成代码的GCC编译器套件。
• 烧录与驱动 (Hiburn + CH341SER) ：
  • CH341SER.EXE ：这是USB转串口芯片CH340/CH341的Windows驱动程序。安装后，Windows才能识别连接开发板的USB口为一个串行端口（如COM3）。
  • Hiburn ：这是海思提供的专用烧录工具。它通过串口与开发板上的Bootloader通信，将编译好的二进制文件（.bin）写入到开发板的Flash存储中。

3. Linux服务器环境搭建实战与避坑指南

这是整个搭建过程中最复杂、最容易出错的一环。我们一步一步来，我会把每个命令的作用和可能遇到的问题都解释清楚。

3.1 基础系统准备：Shell与网络

假设你已经安装好了一个Ubuntu 18.04或20.04的Linux环境（实体机或虚拟机）。

第一步：确保Shell是Bash 在终端中执行 ls -l /bin/sh 。如果显示 /bin/sh -> bash 或 /bin/sh -> /bin/bash ，那么恭喜，这一步跳过。 如果不是，很可能指向了 dash 。 dash 是一个更轻量、更严格的Shell，但HarmonyOS的一些构建脚本可能依赖Bash的特定语法。修改方法如下：

# 交互式选择（推荐）
sudo dpkg-reconfigure dash

在弹出的蓝色文本界面中，用键盘方向键选择“No”，然后回车。系统会自动将 /bin/sh 重新链接到 bash 。

踩坑记录 ：我曾在一个精简版的Docker镜像里构建，默认就是 dash ，导致运行 ./build.py 脚本时报出一堆语法错误，排查了半天才发现是Shell的问题。所以这是必须检查的第一步。

第二步：配置软件源与基础工具 为了后续安装顺畅，建议先更新软件源并安装一些基础开发包。

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y vim git curl wget build-essential

• build-essential ：包含了gcc, g++, make等最基础的编译工具，是很多其他软件编译的前提。

3.2 Python环境部署：细节决定成败

HarmonyOS构建要求Python 3.7+。Ubuntu 18.04默认可能是3.6，20.04默认是3.8。先检查： python3 --version 。

情况一：版本已满足 如果显示3.7或更高，可以直接安装pip和必要的Python模块。

情况二：需要安装或升级Python 3.8 以安装Python 3.8为例：

# 1. 安装编译依赖
sudo apt-get install -y gcc g++ make zlib1g-dev libffi-dev libssl-dev libncurses5-dev libsqlite3-dev libreadline-dev libbz2-dev

# 2. 下载Python 3.8.5源码包 (如果服务器下载慢，可以在Windows下载后用MobaXterm的SFTP功能拖过去)
wget https://www.python.org/ftp/python/3.8.5/Python-3.8.5.tgz
# 或者使用官方文档给的链接

# 3. 解压、配置、编译、安装
tar -xzvf Python-3.8.5.tgz
cd Python-3.8.5
# `--enable-optimizations` 选项会进行一些优化，但编译时间很长。对于开发环境可以不加。
./configure --prefix=/usr/local/python3.8 --enable-optimizations
make -j$(nproc)  # 使用所有CPU核心并行编译，加快速度
sudo make install

关键步骤：创建软链接 安装后，系统的 python3 和 pip3 可能还是指向旧版本。我们需要让它们指向新安装的3.8。

# 备份旧的链接（如果有）
sudo mv /usr/bin/python3 /usr/bin/python3.bak
sudo mv /usr/bin/pip3 /usr/bin/pip3.bak

# 创建新的软链接，指向我们安装的版本
sudo ln -s /usr/local/python3.8/bin/python3.8 /usr/bin/python3
sudo ln -s /usr/local/python3.8/bin/pip3.8 /usr/bin/pip3

# 验证
python3 --version  # 应显示 Python 3.8.5
pip3 --version     # 应显示对应版本

安装必要的Python模块

# 升级pip本身
sudo pip3 install --upgrade pip

# 安装setuptools和kconfiglib (用于图形化配置)
sudo pip3 install setuptools kconfiglib

# 安装加密相关依赖（用于签名等操作）
sudo pip3 install pycryptodome six ecdsa

重要提示 ：安装 kconfiglib 或 pycryptodome 时，如果遇到关于 lsb_release 的错误（ Command '('lsb_release', '-a')' returned non-zero exit status 1 ），这是因为某些最小化系统缺少这个命令。解决方法：

sudo apt-get install -y lsb-release

如果还是不行，可以按文档所说找到并删除有问题的 lsb_release 文件（通常不推荐），但安装包是最正本清源的方法。

3.3 构建工具三剑客：Gn, Ninja, SCons

安装SCons 最简单的方式是使用apt安装：

sudo apt-get install -y scons
scons -v  # 验证，应输出版本号（如3.0.1）

如果软件源版本太低，才需要从源码编译，一般不需要。

安装Gn和Ninja 官方文档提供了百度网盘的链接。如果下载不便，也可以尝试从其他开源镜像站寻找预编译的二进制文件。这里假设你已经下载了 gn.1523.tar 和 ninja.1.9.0.tar 。

# 1. 创建工具目录并解压（我习惯放在用户主目录下）
cd ~
tar -xvf gn.1523.tar   # 这会解压出一个 gn 目录
tar -xvf ninja.1.9.0.tar # 这会解压出一个 ninja 目录

# 2. 配置环境变量
# 编辑 ~/.bashrc 文件
vim ~/.bashrc
# 在文件末尾添加以下两行，请根据你的实际解压路径调整
export PATH=~/gn:$PATH
export PATH=~/ninja:$PATH

# 3. 让环境变量立即生效
source ~/.bashrc

# 4. 验证安装
gn --version  # 应输出版本信息
ninja --version # 应输出 1.9.0

安装交叉编译工具链 gcc_riscv32 同样，假设你已经下载了 gcc_riscv32-linux-7.3.0.tar.gz 。

# 1. 解压到 /opt 目录（通常用于存放第三方软件）
sudo tar -xvf gcc_riscv32-linux-7.3.0.tar.gz -C /opt/

# 2. 配置环境变量
vim ~/.bashrc
# 在文件末尾添加，注意路径是解压后的具体文件夹名
export PATH=/opt/gcc_riscv32/bin:$PATH
# 保存退出后，执行
source ~/.bashrc

# 3. 验证安装
riscv32-unknown-elf-gcc -v

如果成功，你会看到一长串GCC版本信息和配置详情。 这里有个大坑 ：官方文档里解压路径是 ~/ ，但环境变量配置却写了 /opt/gcc_riscv32 ，前后不一致。我建议统一解压到 /opt 下，因为这是更标准的做法。你需要确保 ~/.bashrc 中的路径和工具链的实际存放路径完全一致。

4. Windows工作台配置：打通任督二脉

Linux服务器准备就绪后，我们回到熟悉的Windows环境，进行客户端的配置。

4.1 远程连接：MobaXterm的强大之处

1. 安装MobaXterm ：从官网下载免费的家庭版（Home Edition）即可，功能足够。
2. 建立SSH会话 ：
   • 打开MobaXterm，点击左上角的“Session”。
   • 选择“SSH”。
   • Remote host栏输入你的Linux服务器的IP地址（虚拟机的话，在Ubuntu里用 ip addr 命令查看）。
   • Specify username栏输入你的Linux用户名。
   • 点击OK。首次连接会保存主机密钥，点击Yes。
   • 输入密码，即可登录。 强烈建议勾选“Remember password” ，这样下次就不用再输了。
3. 使用SFTP传输文件 ：MobaXterm左侧边栏会自动显示一个SFTP文件浏览器，列出了你Linux家目录下的文件。你可以像在Windows资源管理器里一样，直接拖拽文件在Windows和Linux之间传输，这比用 scp 命令方便太多了。

4.2 串口驱动与终端：听见开发板的声音

1. 安装CH340/CH341驱动 ：
   • 将BearPi-HM_Nano通过USB线连接到Windows电脑。
   • 打开设备管理器（右键“此电脑”->“管理”->“设备管理器”）。
   • 你应该会看到一个带黄色感叹号的“USB2.0-Serial”或未知设备。
   • 运行 CH341SER.EXE ，点击“安装”。成功后，设备管理器里会出现一个新的“端口（COM和LPT）”，下面会有一个“USB-SERIAL CH340 (COMx)”，记住这个COM号（比如COM3）。
2. 配置串口终端 ：
   • 在MobaXterm中，再次点击“Session”。
   • 选择“Serial”。
   • 在“Serial port”下拉菜单中选择你刚才记下的COM口（如COM3）。
   • “Baud rate”设置为 115200 （这是Hi3861默认的串口波特率）。
   • 其他参数（Data bits: 8, Stop bits: 1, Parity: None, Flow control: None）保持默认。
   • 点击OK。这会打开一个串口终端窗口。
   • 给开发板重新上电（按一下RST键），你应该会在串口终端里看到海思Bootloader的启动日志，最后可能停在 hisilicon 的命令行提示符下。这说明串口通信正常。

4.3 代码编辑器的选择与配置

1. 安装VS Code ：直接从官网下载安装。
2. 安装有用插件 ：
   • C/C++ (Microsoft)：提供代码跳转、智能提示。
   • Code Runner ：可以快速运行单个文件（虽然HarmonyOS项目不直接这样用，但很方便）。
   • （可选） Remote - SSH (Microsoft)：如果你希望直接在VS Code里远程编辑Linux服务器上的代码，可以安装这个插件。但对于初学者，先用MobaXterm的SFTP下载代码到Windows编辑，再传回去，流程更清晰。

5. 获取源码、编译与烧录全流程实录

环境全部配好，终于到了最激动人心的环节：让代码在板子上跑起来。

5.1 获取HarmonyOS源码

对于BearPi-HM_Nano，最方便的是从小熊派官方的Gitee仓库获取适配好的代码。 在MobaXterm的Linux终端中操作：

# 1. 找一个合适的目录，比如家目录下创建一个workspace
cd ~
mkdir harmonyos
cd harmonyos

# 2. 使用git克隆代码仓库（如果网速慢，可以在Windows用下载工具下zip包，再用SFTP上传解压）
git clone https://gitee.com/bearpi/bearpi-hm_nano.git --recursive
# `--recursive` 参数很重要，它会同时下载子模块（比如内核源码）。

cd bearpi-hm_nano

这个仓库已经为BearPi-HM_Nano做好了适配，包含了许多示例程序。

5.2 首次编译：从命令行到bin文件

HarmonyOS LiteOS-M内核使用 hb 工具进行构建。我们需要先安装 hb 。

# 在bearpi-hm_nano根目录下执行
python3 -m pip install --user ohos-build
# 安装后，将hb工具所在路径（通常是 ~/.local/bin）添加到PATH
echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 验证hb安装
hb --help

现在开始编译一个最简单的示例—— hello_world 。

# 1. 设置目标开发板（Hi3861）
hb set

执行 hb set 后，会出现一个图形化界面（如果没出现，检查 kconfiglib 是否安装成功）。用方向键选择 bearpi-hm_nano ，然后回车。

# 2. 选择要编译的应用程序路径
# 此时会再次出现一个菜单，让你选择产品。对于BearPi，通常选择 `bearpi_hm_nano` 或类似的选项，回车确认。
# 不同的仓库可能稍有不同，请根据屏幕提示选择。

# 3. 开始编译
hb build -f

• -f 表示全量编译，会清理之前的编译产物。第一次编译必须加这个参数。

编译过程会持续几分钟，你会看到大量的编译命令滚动。如果一切环境配置正确，最终会看到 “BUILD SUCCESS” 的字样，并在 out/bearpi_hm_nano/bearpi_hm_nano/ 目录下找到生成的 Hi3861_wifiiot_app_allinone.bin 文件。这个文件就是我们最终要烧录到开发板的固件。

编译过程常见问题排查 ：

• gn: command not found 或 ninja: command not found ：环境变量没生效。请确认 ~/.bashrc 中的路径正确，并执行了 source ~/.bashrc 。可以在终端直接输入 echo $PATH 查看路径是否包含。
• riscv32-unknown-elf-gcc: command not found ：同上，交叉编译工具链路径未正确设置。
• Python模块缺失 ：仔细检查 kconfiglib , pycryptodome , ecdsa , six 是否都已安装成功。
• 内存不足 ：虚拟机内存分配过小，编译可能失败。建议增加到4GB或以上。

5.3 烧录程序：让开发板“活”过来

烧录需要在Windows下进行，使用我们之前准备好的Hiburn工具。

1. 准备固件文件 ：将Linux服务器上编译生成的 Hi3861_wifiiot_app_allinone.bin 文件，通过MobaXterm的SFTP功能拖拽到Windows的某个文件夹（例如桌面）。
2. 连接开发板 ：确保开发板通过USB线连接电脑，且串口驱动已安装好。
3. 配置Hiburn ：
   • 打开Hiburn（以管理员身份运行可能更稳妥）。
   • 在 Project -> Setting 或直接在界面上选择：
     • COM Port : 选择你的开发板对应的串口（如COM3）。
     • Baud ：设置为 921600 （这是Hi3861的烧录波特率，与串口调试的115200不同！）。
   • 点击 Select file 按钮，选择你刚才下载到桌面的 .bin 文件。
   • 勾选 Auto burn 复选框。
4. 进入烧录模式 ：这是最关键的一步！Hi3861芯片需要在上电的瞬间进入烧录模式。
   • 先按住开发板上的 “FLASH” 按键 （或标注为BOOT的按键）不放。
   • 然后，短暂地按一下 “RST” 复位按键 。
   • 此时，松开“FLASH”键。这个操作让芯片从系统Flash启动转为从USB烧录接口启动。
5. 开始烧录 ：在Hiburn中，点击 Start 按钮。如果操作正确，你会看到进度条开始走动，并且下方的日志框显示“Connecting...”“Erasing...”“Programming...”“Verifying...”等字样。
6. 烧录成功 ：当进度条走完，并显示“Execution Successful”或类似的成功提示时，表示烧录完成。
7. 运行程序 ：点击Hiburn的 Stop 按钮，然后按一下开发板的 “RST” 按键 。芯片将正常从Flash启动刚烧录的程序。

5.4 验证成果：串口终端里的“Hello World”

回到MobaXterm之前打开的串口终端窗口（波特率115200）。如果串口终端之前有内容，可以清空一下。按下开发板的RST键复位。

你将在终端里看到Hi3861的启动日志，最后应该会出现来自你应用程序的打印信息。对于 hello_world 示例，你就能看到熟悉的“Hello World!”打印出来。至此，恭喜你！你已经成功完成了从环境搭建、源码编译到程序烧录、运行的全过程，BearPi-HM_Nano开发板已经在你的掌控之中了。

6. 环境搭建中的典型问题与解决思路速查表

即使按照指南操作，也难免会遇到问题。这里我总结了一份速查表，涵盖了从环境配置到编译烧录的常见“坑”。

问题现象	可能原因	排查步骤与解决方案
MobaXterm SSH连接失败	1. Linux服务器IP地址错误。 2. Linux SSH服务未开启。 3. 防火墙阻止。	1. 在Linux终端用 ip addr 或 ifconfig 确认IP。 2. 运行 sudo systemctl status ssh 检查服务状态，未安装则 sudo apt-get install openssh-server 。 3. 检查虚拟机网络是否为桥接模式，或主机防火墙是否放行了22端口。
hb set 无图形化界面	1. kconfiglib 未安装或版本不对。 2. 终端不支持图形（如纯SSH）。	1. 确认已安装 kconfiglib ：`pip3 list
编译报错 gn: not found	Gn/Ninja环境变量未正确设置。	1. echo $PATH 查看路径。 2. 检查 ~/.bashrc 中路径是否正确，特别是路径中不能有中文或特殊字符。 3. 执行 source ~/.bashrc 后重试。
编译报错 riscv32-unknown-elf-gcc 相关错误	交叉编译工具链问题。	1. 确认工具链已解压，且路径正确添加到 PATH 。 2. 在工具链的 bin 目录下直接执行 ./riscv32-unknown-elf-gcc -v 看是否正常。 3. 检查工具链是否为32位版本，64位系统可能需要安装32位兼容库： sudo apt-get install lib32z1 。
烧录时Hiburn无法连接	1. 串口号选择错误。 2. 波特率不是921600。 3. 未正确进入烧录模式。 4. 驱动问题。	1. 在设备管理器中确认COM口。 2. 确认Hiburn波特率为921600。 3. 严格按照步骤 ：先按住FLASH键，再点按RST键，然后松开FLASH键。 4. 重新安装CH340驱动，或尝试换一个USB口。
烧录成功但串口无输出	1. 串口终端波特率不是115200。 2. 程序本身无打印或打印被关闭。 3. 开发板供电不足。	1. 检查MobaXterm串口会话的波特率是否为115200。 2. 确认烧录的固件是包含应用程序的 allinone.bin ，并检查代码中是否有打印语句（如 printf ）。 3. 使用质量好的USB线，并直接连接电脑后置USB口，避免使用扩展坞。
Python模块安装超时或失败	网络问题，连接PyPI官方源慢。	更换为国内镜像源，如阿里云、清华源。 pip3 install [模块名] -i https://mirrors.aliyun.com/pypi/simple/

最后，我想分享一个最重要的心得：嵌入式开发，尤其是环境搭建，本质上是一个“精确”的活儿。任何一个路径错误、一个版本不匹配、一个步骤顺序颠倒，都可能导致失败。我的建议是， 严格按照一份可靠的指南操作，并充分理解每一步的目的 。当遇到报错时，不要慌张，仔细阅读错误信息，它通常已经给出了线索。善用搜索引擎，但要在搜索时加上关键错误代码和关键词（如“Hi3861”、“HarmonyOS”、“hb build error”）。这个从零开始搭建环境并点亮第一盏灯的过程，虽然曲折，但却是你深入理解HarmonyOS开发体系最扎实的第一步。希望这篇超详细的指南能帮你少走弯路，顺利开启你的HarmonyOS之旅。