当前位置：首页 > news >正文

OpenHarmony源码获取全攻略：从HPM到Repo的三种实战方法

news 2026/6/5 18:12:38

1. 项目概述与核心价值

最近在折腾物联网和嵌入式开发的朋友，估计都绕不开一个名字：HarmonyOS。作为面向全场景的分布式操作系统，它确实给设备互联带来了新的想象空间。但对于我们这些习惯了在STM32、ESP32上写裸机或跑FreeRTOS的“老嵌入式”来说，上手一个全新的操作系统，第一步“获取源码”就可能让人有点懵圈。官方文档虽然全面，但信息分散，对于新手，尤其是想快速在真实硬件（比如小熊派的BearPi-HM_Nano开发板）上跑起来的开发者，缺少一个从环境准备到源码落地的“一站式”实操指南。

这正是我写这篇指南的初衷。我将以BearPi-HM_Nano这块非常流行的鸿蒙开发板为例，手把手带你走通获取OpenHarmony源码的三种主流方式。这不仅仅是把命令列出来，更重要的是，我会结合自己踩过的坑，告诉你每种方式背后的设计逻辑、适用场景，以及在不同操作系统（特别是Linux）下的详细配置要点。无论你是想快速体验、进行组件化开发，还是需要深度定制和源码学习，都能在这里找到最适合你的路径。文章最后，我还会带你快速浏览源码目录结构，让你拿到代码后不再是一头雾水，而是能清晰地知道每个文件夹是干什么的，为后续的开发和调试打下坚实基础。

2. 环境准备：构建稳固的基石

在开始下载任何源码之前，一个正确且干净的环境是成功的一半。OpenHarmony的编译和组件管理工具链对运行环境有明确要求，跳过或马虎对待这一步，后续很可能遇到各种千奇百怪的报错。

2.1 操作系统选择与建议

官方推荐在Linux环境下进行OpenHarmony的开发，尤其是Ubuntu 18.04及以上版本。这是经过最充分测试的环境，能最大程度避免因系统差异导致的工具链兼容性问题。

为什么是Linux？核心原因在于其强大的命令行工具链、稳定的文件系统以及对开源构建工具（如gn、ninja）的原生友好支持。Windows下的各种路径、权限和符号链接问题，在开发初期就可能消耗你大量精力。
实操建议：如果你主要使用Windows，强烈建议不要直接在Windows上搞。最佳实践是：
1. 使用WSL2 (Windows Subsystem for Linux 2):在Windows 10/11上安装WSL2并选择一个Ubuntu发行版。这几乎能获得原生Linux的体验，且与Windows文件系统互通方便。注意：请确保WSL2版本支持systemd（较新版本默认支持），因为一些服务管理可能需要它。
2. 使用虚拟机（如VMware, VirtualBox）：安装一个完整的Ubuntu系统。这种方式资源隔离性好，但性能略有损耗，且文件共享需要额外配置。
3. 物理机安装双系统或纯Linux：对于长期投入的开发者，这是最纯粹、性能最好的选择。

我个人在项目中主要使用Ubuntu 20.04 LTS on WSL2，兼顾了便利性和兼容性，后续的所有命令行操作都将基于此环境。

2.2 Node.js与npm的安装与配置

OpenHarmony的组件包管理工具HPM（HarmonyOS Package Manager）基于Node.js开发，因此第一步就是安装正确版本的Node.js。

版本要求：官方推荐Node.js 12.x (npm 6.14.4+) 或更高版本，个人实测Node.js 14.x 或 16.x的LTS版本更为稳定。避免使用太老的版本（如10.x）或太前沿的奇数版本（如17.x, 19.x）。
安装方法（推荐使用NodeSource仓库）：直接下载压缩包有时会遇到环境变量问题。更稳妥的方式是通过NodeSource提供的安装脚本。

# 1. 以root权限更新软件包列表并安装一些基础工具 sudo apt update sudo apt install -y curl wget git # 2. 下载并执行NodeSource安装脚本（这里以Node.js 16.x为例） curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash - # 3. 安装Node.js和npm sudo apt install -y nodejs # 4. 验证安装 node --version # 应输出 v16.x.x npm --version # 应输出 8.x.x 或更高

避坑指南：
- 权限问题：避免使用sudo来运行npm install -g（安装全局包），这可能导致后续模块权限混乱。如果遇到EACCES错误，最佳解决方案是使用Node.js官方推荐的权限修正方式，或者使用nvm（Node Version Manager）来管理Node.js版本，它能完美解决全局包安装路径的权限问题。
- 镜像加速：如果npm install速度慢，可以切换为国内镜像（如淘宝npm镜像）。
```
npm config set registry https://registry.npmmirror.com/
```

2.3 HPM-CLI命令行工具的安装与验证

HPM-CLI是管理OpenHarmony组件包的核心工具，通过npm安装。

# 安装hpm-cli工具，-g表示全局安装 npm install -g @ohos/hpm-cli # 安装完成后，验证是否成功 hpm -V # 注意是大写的V，查看版本号

如果执行hpm -V提示“命令未找到”，说明全局安装的路径没有加入到系统的PATH环境变量中。使用npm安装的全局包通常位于~/.npm-global/bin或/usr/local/lib/node_modules对应的bin目录下。你可以通过以下命令找到它并临时添加：

# 查找hpm的实际安装路径 which hpm # 如果找不到，尝试查找npm的全局安装路径 npm config get prefix # 假设输出是 /home/yourname/.npm-global # 那么hpm可能在 /home/yourname/.npm-global/bin/hpm # 将上述bin目录添加到当前shell的PATH中 export PATH=$PATH:/home/yourname/.npm-global/bin

为了让每次打开终端都生效，可以将上面的export行添加到你的shell配置文件（如~/.bashrc或~/.zshrc）中，然后执行source ~/.bashrc。

注意：有些教程会教你用sudo ln -s创建软链接到/usr/bin，这在某些系统上可行，但并非最佳实践，尤其是当你使用nvm管理多版本Node.js时，软链接可能会失效。优先推荐通过配置PATH环境变量来解决。

3. 源码获取方式一：HPM网站可视化获取（新手友好）

这种方式最适合初学者和希望快速构建原型的开发者。它通过网页界面操作，直观地选择解决方案和组件，由系统打包生成基础工程。

3.1 适用场景与核心逻辑

场景：你刚接触OpenHarmony，手上有一块BearPi-HM_Nano，想以最快速度搭建一个能编译、能烧录、能运行的基础开发环境，并参考官方示例开始学习。
逻辑：HPM网站（HarmonyOS Package Manager）相当于一个“应用商店”，里面存放了针对不同开发板预配置好的“解决方案包”（Solution）。这个包本身不包含所有源代码，而是一个“菜单”（bundle.json），定义了需要哪些组件（如内核、驱动、子系统）及其版本。你下载的是一个“食谱”，执行hpm install才是根据“食谱”去市场（代码仓库）采购所有“食材”（源码组件）。

3.2 分步操作详解

访问HPM网站：打开浏览器，访问OpenHarmony的包管理网站（通常搜索“OpenHarmony HPM”即可找到）。在网站上找到“解决方案”或“Boards”区域。
查找解决方案：在搜索框中输入“BearPi-HM_Nano”，找到对应的解决方案页面。点击进入，你会看到该方案的详细介绍、版本信息、依赖关系等。
定制与下载：
- 在解决方案页面，通常有一个“下载”或“定制”按钮。点击后，可能会进入一个定制界面（如原文中图3所示）。在这里，你可以看到该解决方案包含的所有组件列表。
- 对于纯新手，强烈建议直接使用默认配置，不要做任何修改。直接点击“下载”按钮。系统会生成一个名为bearpi_hm_nano.zip（或类似名称）的压缩包，并下载到你的本地。
- 定制（可选）：如果你有一定经验，可以在这里关闭一些你暂时用不到的组件（例如某些传感器驱动、示例应用），以简化工程。也可以添加一些额外的组件。但请注意，随意裁剪可能导致功能缺失或编译错误。

3.3 本地解压与组件安装

假设你将下载的bearpi_hm_nano.zip放到了Linux系统的~/projects/目录下。

# 1. 进入你的项目目录 cd ~/projects # 2. 解压下载的解决方案包 unzip bearpi_hm_nano.zip -d bearpi_project cd bearpi_project # 3. 关键步骤：安装所有依赖组件 hpm install

执行hpm install后，CLI工具会做以下几件事：

读取当前目录下的bundle.json文件（这就是你的“食谱”）。
解析其中声明的所有依赖（dependencies）。
从配置的仓库（默认是OpenHarmony的官方仓库）依次下载这些组件的源码包。
将所有组件解压并放置到项目目录下的ohos_bundles文件夹中，并建立正确的依赖链接。

此时，完整的、可编译的OpenHarmony源码才真正存在于你的bearpi_project目录中。ohos_bundles里存放的是各个组件的源码，而项目根目录下的文件主要是配置文件、编译脚本和入口。

3.4 首次编译验证

环境是否真正准备好，用编译来检验是最直接的方法。

# 在项目根目录（即 bearpi_project 目录）下执行编译命令 hpm dist

hpm dist命令会启动完整的编译流程，包括配置、生成Ninja文件、调用编译器链等。整个过程可能需要10-30分钟，取决于你的电脑性能。如果最终看到类似“BUILD SUCCESS”或“build success”的输出，并在out/bearpi_hm_nano/目录下生成了Hi3861_wifiiot_app_allinone.bin这样的固件文件，那么恭喜你，从源码获取到编译的完整链路已经打通！

实操心得：第一次使用HPM网站下载，最容易出错的地方就是混淆了“下载解决方案包”和“获取完整源码”。很多人解压zip包后就直接去找代码，发现里面空空如也，只有几个json文件，就以为下载错了。记住，那个zip是“菜单”，hpm install才是“买菜”。

4. 源码获取方式二：HPM命令行工具获取（高效灵活）

当你已经熟悉了OpenHarmony的项目结构，或者需要基于一个现有项目进行组件升级、替换时，命令行方式更加高效和灵活。

4.1 适用场景与核心逻辑

场景：
- 你已有一个OpenHarmony项目，只想更新或替换其中的某个特定组件（例如，更新kernel_liteos_m到新版本）。
- 你希望完全从零开始，通过命令行初始化一个纯净的项目，然后手动添加所需组件，享受最大的控制权。
- 在CI/CD（持续集成/持续部署）流水线中，自动化地创建和构建项目。
逻辑：这种方式跳过了网页界面，直接通过hpm init和hpm i（install的简写）等命令来操作。它直接与远程的HPM仓库交互，拉取组件的元信息和源码。项目结构完全由命令行创建和定义。

4.2 从零创建项目并添加开发板组件

让我们一步步创建一个全新的BearPi-HM_Nano项目。

# 1. 创建一个专门的工作目录并进入 mkdir ~/my_ohos_project && cd ~/my_ohos_project # 2. 初始化一个默认的hpm项目 hpm init -t default

执行hpm init -t default后，会在当前目录生成一个最基本的项目骨架，包括bundle.json（项目描述和依赖声明文件）、README.md等。你可以打开bundle.json看看，里面主要定义了项目名、版本、描述等元信息，dependencies部分是空的。

# 3. 安装BearPi-HM_Nano开发板的核心解决方案组件 hpm i @bearpi/bearpi_hm_nano

这条命令是核心。@bearpi/bearpi_hm_nano是开发板解决方案在HPM仓库中的唯一标识符（包名）。hpm i命令会：

向HPM仓库查询这个包的最新版本（或你指定的版本）信息。
解析这个包自身的所有依赖（它会依赖内核、驱动、HAL层等无数其他组件）。
递归地下载所有依赖的组件到ohos_bundles目录。
更新你本地的bundle.json文件，将@bearpi/bearpi_hm_nano及其解析出的正确版本号添加到dependencies中。

这个过程可能会下载几百兆甚至上G的数据，请保持网络通畅。完成后，你会看到Install successfully!的提示。

4.3 组件管理与依赖解析

通过命令行，你可以非常精细地管理组件。

安装特定版本：hpm i @bearpi/bearpi_hm_nano@1.0.0（安装1.0.0版本）
更新组件：hpm update @bearpi/bearpi_hm_nano（更新到仓库中的最新版本）
移除组件：hpm remove @bearpi/bearpi_hm_nano（从项目中移除，但已下载到ohos_bundles的源码可能还在）
查看依赖树：hpm dependencies可以查看当前项目所有依赖的树状结构，对于理解项目构成和排查依赖冲突非常有用。

依赖冲突的解决：这是组件化开发中常见的问题。例如，组件A依赖内核版本>=1.1.0，而组件B依赖内核版本<=1.0.5。当执行hpm i时，HPM解析器会尝试找到一个能满足所有依赖的版本，如果找不到就会报错。此时，你需要手动干预，要么寻找兼容的组件版本，要么联系组件维护者。

4.4 编译与构建

项目初始化并安装好组件后，编译命令与方式一相同：

hpm dist

你也可以使用更底层的编译命令，这有助于在出错时看到更详细的日志：

# 在项目根目录执行 python build.py BearPi-HM_Nano

hpm dist本质上是对python build.py等一系列命令的封装。直接使用python build.py可以传递更多参数，例如指定编译类型（debug/release）、编译子系统等。

注意事项：命令行方式赋予了开发者极大的自由，但“能力越大，责任越大”。你需要自行管理bundle.json文件，确保依赖声明的准确性。在团队协作中，务必将此文件纳入版本控制（如Git），确保所有成员的环境一致。

5. 源码获取方式三：从代码仓库直接克隆（深度定制与贡献）

这是最“硬核”的获取方式，直接面对Git仓库。它适用于需要对OpenHarmony进行深度定制、基线化维护、问题修复或向社区贡献代码的开发者。

5.1 适用场景与核心逻辑

场景：
- 厂商定制：芯片原厂或设备制造商需要基于某个OpenHarmony稳定分支（如OpenHarmony 3.2 Release）建立自己的产品基线，进行深度定制后再分发给下游客户。
- 源码学习与研究：你想深入研读某一子系统（如分布式软总线dsoftbus）的代码实现。
- 问题修复与贡献：你在开发中发现了一个OpenHarmony的bug，并定位到了具体仓库的代码，需要拉取该仓库代码进行修复，并提交PR（Pull Request）。
- 认证需求：产品需要通过OpenHarmony官方兼容性认证，需要基于官方主干代码进行开发。
逻辑：OpenHarmony采用多仓库的代码管理模式。整个系统被拆分成数百个独立的Git仓库，通过一个名为repo的Python工具进行统一管理。repo是Google为管理Android源码而开发的工具，它通过一个清单（manifest）文件来定义需要拉取哪些仓库、各自的地址和分支。这种方式使得每个模块可以独立开发、版本化和复用。

5.2 准备工作：Git与Repo工具

安装Git：sudo apt install git

配置Git用户信息（必须，否则无法提交代码）：

git config --global user.name "Your Name" git config --global user.email "your.email@example.com"

安装Repo工具：Repo本身是一个Python脚本，我们把它下载到可执行路径下。
```
# 创建bin目录（如果不存在）并加入PATH mkdir -p ~/.bin export PATH=~/.bin:$PATH # 下载Repo工具 curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo chmod a+x ~/.bin/repo
```
（如果Google地址无法访问，可以使用国内镜像，如清华源：curl -sSL 'https://mirrors.tuna.tsinghua.edu.cn/git/git-repo' > ~/.bin/repo）

5.3 克隆完整代码仓库

这里以克隆小熊派维护的BearPi-HM_Nano专用代码仓为例。这通常是一个已经整合好的、针对该开发板的“厂商适配层”仓库，它可能通过submodule或特定的manifest引用了OpenHarmony的核心仓库。

# 1. 创建一个工作目录 mkdir ~/ohos_source && cd ~/ohos_source # 2. 克隆小熊派的主仓库（这里假设其提供了完整的集成） git clone https://gitee.com/bearpi/bearpi-hm_nano.git -b master cd bearpi-hm_nano # 3. 重要：查看仓库的README或文档，确认拉取子模块或依赖的命令。 # 常见情况是使用 `git submodule` 来初始化并更新子模块。 git submodule init git submodule update --recursive # 这个过程会拉取所有链接的OpenHarmony子仓库，耗时较长。

另一种更标准的方式是使用OpenHarmony官方manifest：如果你需要最原始、最完整的OpenHarmony代码，应该从官方manifest仓库开始。

# 1. 创建工作目录 mkdir ~/openharmony && cd ~/openharmony # 2. 初始化repo客户端，指定分支和manifest仓库 repo init -u https://gitee.com/openharmony/manifest.git -b master --no-repo-verify # 3. 同步所有代码仓库（这将下载数十GB数据，时间很长） repo sync -c # -c 表示只同步当前manifest指定的分支，节省时间

5.4 代码结构管理与编译

通过Repo拉取的代码，其目录结构是庞大的、扁平的。你会在根目录下看到kernel/liteos_m,foundation,vendor（这里可能就包含bearpi/bearpi_hm_nano）等目录。

针对BearPi-HM_Nano的编译，你需要找到对应的产品配置文件。通常路径在vendor/bearpi/bearpi_hm_nano/config.json。编译时，需要指定产品名称：

# 在源码根目录执行 python build.py -p bearpi_hm_nano # 或者使用 hb 工具（OpenHarmony构建工具） hb set # 交互式选择产品，选择 bearpi_hm_nano hb build

5.5 深度定制与代码追踪

这种方式的最大优势在于你可以：

任意切换分支/标签：使用git checkout在各个历史版本间穿梭，研究代码演进。
提交修改与创建补丁：在本地仓库修改代码后，可以使用git diff,git format-patch生成补丁，或直接向上游仓库提交PR。
建立私有基线：将官方仓库fork到自己的代码托管平台（如Gitee），然后将其设置为repo init的-u参数，就可以基于此建立公司内部的私有开发基线。

踩坑实录：直接从仓库克隆，最大的挑战是网络和磁盘空间。同步数百个仓库对网络稳定性要求极高，建议使用-j4（4线程）等参数加速，并准备好应对中途失败重试。磁盘空间建议预留100GB以上。此外，多仓库管理对Git操作的要求更高，务必熟悉repo forall,repo start,repo upload等命令。

6. 源码目录结构深度解析

无论通过哪种方式获取源码，最终你都会面对一个庞大的源代码树。理解目录结构是高效开发和调试的前提。下面结合OpenHarmony官方结构和小熊派适配的实际情况，对核心目录进行解读。

6.1 顶层目录概览

下表列出了OpenHarmony源码根目录下最主要的文件夹及其职责：

目录名	核心职责描述	开发者关注度
`applications`	应用层样例。存放系统预置的应用示例，如`camera`、`wifi_iot`（物联网样例）等。这是应用开发者最常接触的目录，你可以在这里参考官方示例，或直接在此目录下新建你的应用。	★★★★★
`base`	基础软件与硬件服务子系统集。这是系统的“核心能力层”，包含了账户、安全、DFX（维测）、泛Sensor、Misc（杂项）服务等几乎所有核心框架和服务的实现。代码量巨大，是系统开发者和架构师需要深入研究的领域。	★★★★☆
`build`	构建子系统。包含了编译构建所需的全部脚本、模板和工具（如`hb`）。如果你想定制编译流程、添加新的产品配置，就需要修改这里的`lite`目录下的内容。	★★★☆☆
`domains`	增强软件服务子系统集。存放一些针对特定领域增强的软件服务，如企业设备管理、IoT服务增强等。普通设备开发者初期接触较少。	★★☆☆☆
`drivers`	驱动子系统。包含内核态（HDF框架）和用户态（如Peripheral API）的驱动框架及具体驱动（如WLAN、Sensor、Display）。驱动开发者的主战场。	★★★★☆
`foundation`	系统基础能力子系统集。这是系统的“基石”，包含了分布式任务调度、通信（软总线）、数据管理、公共基础库等最核心的底层框架。系统底层开发必看。	★★★★★
`kernel`	内核。存放OpenHarmony支持的内核源码，如`liteos_m`（面向轻量设备的轻内核）。内核开发者或需要深度优化性能、调度时关注。	★★★☆☆
`prebuilts`	预编译工具链。存放了编译所需的交叉编译器（如gcc-arm-none-eabi）、Python解释器、mkimage等工具。通常不需要修改，但编译出错时需要确认工具链版本是否正确。	★★☆☆☆
`test`	测试子系统。包含开发者测试（XTS兼容性测试套件）和系统测试框架及相关用例。进行产品认证或保证代码质量时需要用到。	★★★☆☆
`utils`	公共工具集。包含一些系统通用的工具类代码，如文件操作、KV存储（litekv）、系统属性等。	★★★☆☆
`vendor`	厂商适配层。这是设备开发者最关键的目录。各芯片厂商（如HiSilicon、Rockchip）或开发板厂商（如BearPi）的适配代码都放在这里。例如，`vendor/bearpi/bearpi_hm_nano/`就包含了该开发板的板级配置、驱动适配、HDF配置、启动参数等。你的大部分板级定制工作都在这里完成。	★★★★★
`build.py`	顶层编译脚本。执行`python build.py [product_name]`就是调用这个脚本，它负责解析参数、调用`build/lite`下的构建系统。	★★☆☆☆

6.2 关键目录联动关系解析

理解目录结构的关键在于理解它们如何协作。以一个简单的“Wi-Fi联网”应用为例：

应用入口 (applications/sample/wifi-iot/app): 你在这里编写main.c，调用Wi-Fi连接的API。
API实现 (foundation/communication/wifi): 应用调用的Wi-Fi API，其具体实现在foundation的通信子系统里。它可能是一个客户端存根（stub）。
驱动框架 (drivers/framework): Wi-Fi服务通过HDF（硬件驱动框架）与底层驱动交互。HDF提供了标准的驱动模型。
具体驱动 (drivers/adapter/khdf/linux/wifi): 这里是针对具体Wi-Fi芯片（如Hi3861内置的WLAN）的HDF驱动实现。
厂商配置 (vendor/bearpi/bearpi_hm_nano/hdf_config): 在vendor目录下，有HDF的配置文件（.hcs文件），它定义了板子上有哪些设备、绑定哪个驱动。例如，它告诉系统“wlan0”这个设备使用“hi3881_wifi”驱动。
内核支持 (kernel/liteos_m/drivers/wifi): 内核中提供了Wi-Fi协议栈和与HDF对接的接口。

当你执行hpm dist或python build.py时，构建系统会从vendor读取产品配置，然后按依赖关系依次编译kernel、drivers、foundation、applications等目录下的组件，最终链接成二进制固件。

6.3 开发者工作流与目录对应

根据你的角色，你的主要工作目录会有所不同：

应用开发者：90%的时间在applications/下，偶尔需要查看foundation/下的API说明或utils/下的工具库。
驱动开发者：工作在drivers/和vendor/[your_company]/[your_product]/目录下，编写或适配HDF驱动，并配置.hcs文件。
系统定制工程师：重点关注vendor/目录，修改板级配置、启动脚本、系统参数，并可能裁剪base/或foundation/中的子系统。
贡献者/研究者：根据你关注的模块，深入对应的子系统目录，如研究分布式能力就去foundation/distributeddatamgr/和foundation/communication/dsoftbus/。

7. 常见问题与排查技巧实录

在实际操作中，你几乎一定会遇到各种问题。这里我整理了从环境准备到编译运行全流程中最常见的“坑”及其解决方案。

7.1 环境配置类问题

问题1：执行hpm -V或node --version提示“命令未找到”。

原因：安装路径未加入系统PATH环境变量。
排查：
1. 使用which node或whereis node查找node可执行文件的实际位置（例如/home/user/.nvm/versions/node/v16.15.0/bin/node）。
2. 检查当前shell的PATH变量：echo $PATH，看上述路径是否在其中。
解决：
- 临时解决：export PATH=/path/to/your/node/bin:$PATH
- 永久解决：将上面的export命令添加到~/.bashrc或~/.zshrc文件末尾，然后执行source ~/.bashrc。

问题2：npm install -g @ohos/hpm-cli安装失败，报权限错误（EACCES）。

原因：通常是因为使用sudo安装了Node.js，或者npm的全局安装目录权限不对。

解决（推荐方案）：

彻底卸载当前Node.js/npm。
使用nvm（Node Version Manager）重新安装Node.js。nvm会将所有内容安装到你的用户目录下，完美解决权限问题。

# 安装nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash # 重启终端或 source ~/.bashrc # 安装Node.js nvm install 16 nvm use 16 # 此时再安装hpm-cli npm install -g @ohos/hpm-cli

7.2 源码获取与依赖安装类问题

问题3：hpm install速度极慢或卡住不动。

原因：HPM默认仓库服务器可能在海外，网络不稳定。
解决：为hpm配置国内镜像源。
1. 查看当前配置：hpm config get registry
2. 设置为国内镜像（例如华为云镜像）：hpm config set registry https://repo.huaweicloud.com/harmonyos/ohpm/
3. 再次执行hpm install。

问题4：hpm install失败，提示某个组件下载失败（如404 Not Found）。

原因：组件名称拼写错误、版本不存在，或者该组件已从仓库中移除。
排查：
1. 确认组件名是否正确。可以去HPM网站搜索确认。
2. 检查项目根目录的bundle.json，看依赖的版本号是否过于特殊或不存在。
3. 尝试安装时不指定版本，让hpm选择最新版本：hpm i @bearpi/bearpi_hm_nano。
解决：修正bundle.json中的依赖声明，或联系解决方案的提供者。

问题5：通过Repo同步代码时，某个仓库卡住或失败。

原因：网络问题或仓库本身存在临时问题。
解决：
1. 使用repo sync -c -j4增加同步线程数。
2. 针对单个失败仓库，进入其目录手动执行git fetch和git checkout。
3. 如果某个仓库始终失败，可以尝试在.repo/manifests/default.xml中临时注释掉该仓库的<project>行，先同步其他部分。

7.3 编译构建类问题

问题6：编译错误，提示“找不到 -lxxx” 或 “undefined reference to `xxx‘”。

原因：这是最常见的链接错误。意味着某个库（xxx）没有被正确编译，或者编译顺序有问题，导致链接器找不到它。
排查：
1. 首先检查完整的错误输出，找到是哪个组件或模块报错。
2. 去out/[product_name]/下的构建日志中，搜索该库文件（libxxx.a或libxxx.so）是否生成。
3. 检查bundle.json或BUILD.gn文件，确认该模块是否正确地声明了对xxx库的依赖。
解决：
- 如果是HPM项目，尝试删除ohos_bundles和out目录，重新执行hpm install和hpm dist，确保依赖被完整下载和编译。
- 如果是Repo项目，确认你是否完整地同步了所有仓库，并尝试repo forall -c 'git clean -xdf'清理所有仓库，再重新编译。

问题7：python build.py执行后，很快报错退出，提示“Please run ‘hb set’ first”。

原因：你没有设置要编译的产品。使用hb工具时，需要先通过hb set交互式选择产品。
解决：
- 执行hb set，然后从列表中选择bearpi_hm_nano。
- 或者，直接使用带产品参数的编译命令：python build.py -p bearpi_hm_nano。

问题8：编译成功，但生成的固件烧录后开发板无反应。

原因：
1. 烧录的固件不对（如烧录了错误地址的文件）。
2. 串口配置错误（波特率、端口号）。
3. 开发板启动模式（Boot模式）设置错误。
排查：
1. 确认固件：BearPi-HM_Nano通常需要烧录Hi3861_wifiiot_app_allinone.bin这个文件，并使用HiBurn工具选择正确的烧录地址（如0x0）。
2. 确认串口：使用ls /dev/tty*查看插入开发板后出现的端口，在串口工具（如minicom, picocom）中设置正确的波特率（通常是115200）。
3. 确认Boot模式：参考开发板手册，确保拨码开关或跳线帽处于“Flash启动”模式，而不是“下载模式”。
解决：按照上述排查点逐一检查。最稳妥的方法是找到一份已验证无误的官方教程，严格按照其步骤操作一次，以排除环境问题。