保姆级 | 小鸿AI(WS63) OpenHarmony开发环境搭建+源码编译+烧录全流程【WSL2方案】

开发板：小鸿 AI（海思 WS63 RISC-V + OpenHarmony 6.x 轻量系统）
宿主环境：Windows 11 + WSL2 Ubuntu 22.04
本文目标：从零完成环境搭建、源码拉取编译、镜像烧录全流程，可 1:1 复刻

📌 摘要：本文以 Windows 11 + WSL2 Ubuntu 22.04 为宿主环境，完整记录小鸿 AI（海思 WS63 RISC-V + OpenHarmony 6.x 轻量系统）从零搭建开发环境、拉取源码编译、烧录镜像的全流程。全文分为四步：① 搭建 WSL2 开发环境（安装 Ubuntu、系统依赖、Python 软链接、repo 工具）；② 拉取并编译源码（repo 同步、预编译工具链、hb 构建工具、RISC-V 硬浮点编译器、编译产品选择、执行编译及一键脚本）；③ 镜像烧录到开发板（工具驱动准备、镜像拷贝、BurnTool 烧录、启动验证）；④ 高频踩坑汇总。文中每个步骤均附成功判定标准与避坑指南，并重点强调 5 个极易忽略的关键点：编译产品名须为 nearlink_dk_3863、hb 须用源码树自带版本、RISC-V 编译器须选硬浮点 _fp 版本、烧录进下载模式的时机把控、首次烧录须用 _all.fwpkg 完整镜像。

---

前置核对：开始前请确认

先核对你的环境是否满足要求，避免中途翻车：

项目	要求
主机系统	Windows 10 21H2 / Windows 11 64 位，BIOS 已开启虚拟化（VT-x / AMD-V）
WSL 环境	WSL2（非 WSL1），发行版为 Ubuntu 22.04
Python 版本	3.10.x（Ubuntu 22.04 自带，需配置软链接）
磁盘空间	建议预留 50GB 以上（源码 + 预编译工具约 30~40GB）
运行内存	编译建议 ≥ 8GB
硬件准备	小鸿 AI 开发板（WS63）、USB-TypeC 数据线、CH340/CH341 串口模块

官方资料入口（建议收藏）：

• 官方主页：https://xiaohong.atomgit.com/
• 文档仓库：https://atomgit.com/xiaohong-ai/docs
• 源码仓库：https://atomgit.com/xiaohong-ai/manifest
• 工具下载（烧录工具/驱动/串口助手）：https://atomgit.com/xiaohong-ai/docs/tree/main/tools

本文采用 WSL2 Ubuntu 22.04 原生方案，全程实测可用，所有步骤均附成功判定标准与避坑指南。

关于本文配图：以下截图均加了顶部标题 + 底部关键判断点 + 红色框标注，读图时直接看红框和底部文字即可，跟着做基本不会跑偏。

---

一、搭建 WSL2 开发环境

1.1 安装 WSL2 Ubuntu 22.04

在 Windows 终端（PowerShell）中执行安装命令：

wsl --install -d Ubuntu-22.04

安装完成后设置用户名与密码，执行以下命令确认 WSL 版本：

wsl -l -v

✅ 成功判定：输出中 Ubuntu-22.04 对应的 VERSION 为 2，STATE 为 Running。

⚠️ 注意：如果 VERSION 显示为 1，需执行 wsl --set-version Ubuntu-22.04 2 升级到 WSL2。

1.2 安装系统编译依赖

必须进入 WSL Ubuntu 终端后执行，请勿直接在 PowerShell 中运行 apt 命令：

sudo apt update && sudo apt upgrade -y
sudo apt install -y git git-lfs python3 python3-pip python3-venv curl wget \
  gnupg2 software-properties-common build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev libncursesw5-dev xz-utils \
  tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev lz4

✅ 成功判定：命令执行完毕回到终端提示符，无报错。

⚠️ 避坑：Ubuntu 22.04 中 lz4c 命令由 lz4 软件包提供，无需单独搜索 lz4c 包。
❌ 反面示例：在 PowerShell 里直接粘贴 apt 命令会报 CommandNotFoundException（见下图），务必先 wsl 进入 Ubuntu 再操作。

1.3 配置 Python 软链接

Ubuntu 22.04 默认只有 python3 命令，而大量编译脚本依赖 python 命令，创建软链接：

sudo ln -sf /usr/bin/python3 /usr/bin/python
python --version
python3 --version

✅ 成功判定：两个命令均输出 Python 3.10.x 版本信息。

❌ 反面示例：在 PowerShell 里运行 sudo ln -sf ... 会提示"在此计算机上禁用 Sudo"，这是 Linux 命令，Windows 不支持。

1.4 安装 repo 工具

repo 用于管理多 Git 仓库，这里配置清华镜像加速国内下载：

mkdir -p ~/.local/bin
curl -fsSL https://gitee.com/oschina/repo/raw/master/repo -o ~/.local/bin/repo
chmod +x ~/.local/bin/repo
echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
echo "export REPO_URL='https://mirrors.tuna.tsinghua.edu.cn/git/git-repo/'" >> ~/.bashrc
source ~/.bashrc
repo --version

✅ 成功判定：输出 repo launcher version 2.x（实测 2.8），表示启动器安装完成。

提示：显示 <repo not installed> 属于正常现象，repo 本体将在 repo init 时自动拉取。

---

二、源码拉取与编译

2.1 初始化 repo 并同步源码

mkdir -p ~/xiaohong && cd ~/xiaohong
repo init -u https://atomgit.com/xiaohong-ai/manifest -b main --no-clone-bundle
repo sync -c

同步完成后查看顶层目录：

ls

✅ 成功判定：目录下存在 build、device、vendor、prebuilts 等核心文件夹。

⚠️ 避坑指南

1. 若 repo init 报错 .repo/repo directory: File exists，执行 rm -rf .repo/repo 后重新初始化。
2. 已配置清华镜像源，可大幅提升同步速度，无需额外换源。

2.2 下载 OpenHarmony 预编译工具链

cd ~/xiaohong
bash build/prebuilts_download.sh

该脚本会自动下载 gn、ninja、clang 等编译所需的预编译工具。

✅ 成功判定：终端出现 copy inside cxx finished! 和 update llvm ndk finished! 提示。

⚠️ 避坑：脚本末尾的 npm install 若报错 ENOTEMPTY，执行 rm -rf ~/.npm/_cacache 后重试；WS63 为 LiteOS C 固件，npm 报错不阻塞固件编译，可直接跳过进入下一步。

2.3 安装源码匹配的 hb 构建工具

禁止直接 pip 安装全局 ohos-build，版本不匹配会导致编译失败，必须使用源码树自带版本：

cd ~/xiaohong
pip3 install --user --upgrade build/hb
hb help

✅ 成功判定：执行 hb help 正常输出帮助信息。

⚠️ 注意：hb --version 不是有效参数，会直接报错，请用 hb help 验证安装。
若报错 Please call hb utilities inside source root directory，说明系统存在旧版 hb，重新执行上述安装源码自带版本的命令即可修复。

2.4 配置 RISC-V 交叉编译器（最关键）

SDK 自带两套 RISC-V 编译器，必须使用 hard-float 硬浮点版本，否则会出现 ABI 不匹配链接错误：

cd ~/xiaohong
export PATH="$PWD/device/soc/hisilicon/ws63v100/sdk/tools/bin/compiler/riscv/cc_riscv32_musl_100/cc_riscv32_musl_fp/bin:$PATH"
which riscv32-linux-musl-gcc

✅ 成功判定：which 命令输出的路径中必须包含 _fp/bin。

⚠️ 重中之重

• 软浮点版本路径：cc_riscv32_musl/bin（不能用）
• 硬浮点版本路径：cc_riscv32_musl_fp/bin（必须用）
• 上述 export 仅对当前终端生效，重开终端需重新执行；也可将命令写入 ~/.bashrc 永久生效。

2.5 选择编译产品

产品名不是 xiaohong，必须选择 nearlink_dk_3863，推荐一键配置方式：

hb set -p nearlink_dk_3863

也可执行 hb set，输入 . 回车后在列表中手动选择。

✅ 成功判定：终端提示 Set build cache to ...，产品配置完成。

2.6 执行编译

hb build -f

✅ 成功判定：终端输出 nearlink_dk_3863 build success 与编译耗时，首次编译约 2-3 分钟（ccache 命中后更快）。

编译完成的镜像路径：

ls -lh out/nearlink_dk_3863/nearlink_dk_3863/ws63-liteos-app/*.fwpkg

📌 重要说明

• ws63-liteos-app_all.fwpkg：完整镜像（含 loader），首次烧录必须使用此文件
• ws63-liteos-app_load_only.fwpkg：仅应用镜像，用于后续增量更新，不能单独烧录启动

2.7 一键编译脚本（推荐复用）

将以下内容保存为 build_ws63.sh 放在源码根目录，后续编译直接执行脚本即可，避免重复配置：

#!/bin/bash
cd "$(dirname "$0")"
export PATH="$PWD/device/soc/hisilicon/ws63v100/sdk/tools/bin/compiler/riscv/cc_riscv32_musl_100/cc_riscv32_musl_fp/bin:$PATH"
hb set -p nearlink_dk_3863
hb build -f

添加执行权限：

chmod +x build_ws63.sh

后续编译只需执行：

./build_ws63.sh

---

三、镜像烧录到开发板

3.1 准备烧录工具与驱动

所有工具均从官方文档仓库 tools/ 目录下载（推荐从官方目录页获取，避免第三方转链失效）：

• 官方目录页：https://atomgit.com/xiaohong-ai/docs/tree/main/tools
• BurnTool.rar（烧录工具，绿色版解压即用）：https://raw.gitcode.com/xiaohong-ai/docs/blobs/ee08b2aae36fdf6b5353a67bff2b39a791e7ada9/tools/BurnTool.rar
• CH341_USB转串口驱动（串口驱动，必须安装）：https://raw.gitcode.com/xiaohong-ai/docs/blobs/9f20035563288f2f0224642ed00a49b07786b3d3/tools/CH341_USB%E8%BD%AC%E4%B8%B2%E5%8F%A3Windows_Linux%E9%A9%B1%E5%8A%A8%E7%A8%8B%E5%BA%8F.rar
• UartAssist.rar（串口调试助手，烧完看日志用，可选）：同目录页内下载

注意：ESP32_flash_tools.zip 为小鸿 SE 开发板（ESP32-P4）使用，WS63 无需下载。CH340 / CH341 同驱动，设备管理器可能显示 CH340 或 CH341，均属正常。

3.2 安装串口驱动

1. 解压驱动包，右键以管理员身份运行 CH341SER.EXE，点击安装
2. 用 Type-C 线连接开发板与电脑，开发板电源红灯亮起
3. 打开 Windows 设备管理器 → 端口 (COM 和 LPT)，找到 USB-SERIAL CH34x (COMx)，记下 COM 号

⚠️ 避坑：COM 口号会随 USB 口插拔变化，烧录前请重新确认；若 BurnTool 连接后立刻断开，优先检查 COM 口是否正确。

3.3 镜像文件从 WSL 拷贝到 Windows

烧录工具运行在 Windows 端，需要先把编译好的镜像拷贝出来：

# 在 WSL 终端中执行，将 <你的Windows用户名> 替换为实际用户名（C:\Users\ 下的文件夹名）
cp out/nearlink_dk_3863/nearlink_dk_3863/ws63-liteos-app/ws63-liteos-app_all.fwpkg /mnt/c/Users/<你的Windows用户名>/Desktop/

可在 PowerShell 中验证文件是否存在：

Test-Path "$env:USERPROFILE\Desktop\ws63-liteos-app_all.fwpkg"

✅ 成功判定：返回 True。

3.4 执行烧录

1. 打开 BurnTool.exe
2. 点击菜单 Option → Chip，选择 WS63（WS63E 同系列通用）
3. COM 下拉选择设备管理器中对应的串口号
4. Select file 选择桌面的 ws63-liteos-app_all.fwpkg
5. 勾选 Auto burn 和 Auto disconnect
6. 点击 Connect 按钮
7. 点击 Connect 后 1 秒内，按下开发板的 RST 复位键，让板子进入下载模式；若失败可尝试同时按住左右按键再按复位
8. 等待烧录进度完成

✅ 成功判定：软件底部出现 Execution Successful 提示，显示烧录总大小。

⚠️ 关键避坑

1. 进入下载模式的时机非常关键，BurnTool 握手超时很短，看到 Disconnect 再按就已经超时，需重新操作
2. 首次烧录必须使用 _all.fwpkg 完整镜像，仅烧录应用镜像会导致板子无法启动

3.5 验证启动（可选）

打开串口助手，配置参数：

• 波特率：115200
• 数据位：8，停止位：1，校验：无，流控：无
  给开发板重新上电或按复位键，即可看到 OpenHarmony 启动日志。。

---

四、高频踩坑汇总表

问题现象	核心原因	解决方案
PowerShell 运行 apt/sudo 报错	命令执行环境错误	先执行 wsl 进入 Ubuntu 终端再操作
apt 安装提示 lz4c 包不存在	软件包名称错误	安装 lz4 软件包即可
脚本报错 python 命令不存在	Ubuntu 默认无 python 命令	sudo ln -sf /usr/bin/python3 /usr/bin/python
repo init 提示目录已存在	残留旧 repo 文件	rm -rf .repo/repo 后重试
repo 同步速度极慢	默认使用 Google 源	配置清华 git-repo 镜像（本文已包含）
hb 报错不在源码根目录	全局 hb 版本与源码不匹配	安装源码树自带的 build/hb
编译提示找不到 riscv32 编译器	未加入 PATH 或路径错误	添加 _fp 硬浮点编译器路径到 PATH
链接阶段报 ABI 不匹配	使用了软浮点编译器	切换为 cc_riscv32_musl_fp 硬浮点版本
hb set 找不到对应产品	产品名称错误	选择 nearlink_dk_3863，而非 xiaohong
BurnTool 点 Connect 立刻断开	COM 口错误/未进下载模式	核对 COM 号，点击 Connect 后立即按复位
烧录后板子无法启动	镜像文件选错	首次烧录必须使用 _all.fwpkg 完整镜像

---

写在最后

小鸿 AI WS63 的开发环境搭建，核心难点不在于步骤繁琐，而在于几个极易忽略的细节：

1. 编译产品名是 nearlink_dk_3863 而非 xiaohong
2. hb 工具必须使用源码树自带版本
3. RISC-V 编译器必须选硬浮点 _fp 版本
4. 烧录进入下载模式的时机把控
5. 首次烧录必须使用完整镜像

避开以上关键点，剩下的就是标准的 OpenHarmony 轻量系统开发流程。

如果本文对你有帮助，欢迎 点赞 + 收藏 + 关注，后续会更新更多小鸿 AI 的外设开发与 AI 功能实战教程~