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

保姆级避坑指南：在Ubuntu 20.04上为ESP32搭建OpenHarmony 4.1开发环境（含一键依赖脚本）

news 2026/4/17 5:10:27

保姆级避坑指南：在Ubuntu 20.04上为ESP32搭建OpenHarmony 4.1开发环境

作为一名长期从事嵌入式开发的工程师，我深知在Linux环境下搭建开发环境的痛苦。尤其是当你面对ESP32这样的热门开发板，想要尝试OpenHarmony这样的新兴操作系统时，各种依赖问题、环境配置、编译错误会让你抓狂。本文将带你一步步避开这些坑，用最优雅的方式完成环境搭建。

1. 准备工作：虚拟机与Ubuntu配置

在开始之前，我们需要确保基础环境配置正确。很多开发者在这一步就踩了坑，导致后续问题不断。

1.1 虚拟机资源分配

  • 内存：至少8GB，推荐16GB。OpenHarmony编译过程相当消耗内存，特别是当你想并行编译时。
  • 硬盘空间：建议分配200GB以上。源码、工具链和编译中间文件会占用大量空间。
  • CPU核心：4核以上能显著提升编译速度。

提示：如果你使用的是SSD，编译速度会有明显提升。机械硬盘虽然也能用，但等待时间会很长。

1.2 Ubuntu 20.04安装与优化

Ubuntu 20.04是目前最稳定的选择，官方文档也推荐这个版本。安装完成后，第一件事就是换源：

# 备份原有源列表 sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak # 使用阿里云镜像源 sudo sed -i 's|http://.*archive.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list sudo sed -i 's|http://.*security.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list # 更新软件包索引 sudo apt update && sudo apt upgrade -y

2. 一键安装所有依赖

依赖问题是环境搭建中最令人头疼的部分。我整理了一个完整的依赖列表，并提供了自动化安装脚本。

2.1 依赖脚本详解

创建install_deps.sh文件，内容如下：

#!/bin/bash # 基础工具 base_tools=( git git-lfs curl wget build-essential make cmake ninja-build python3 python3-pip python3-dev openjdk-8-jdk ) # 编译工具链 build_tools=( gcc-multilib g++-multilib flex bison gperf zlib1g-dev libc6-dev-i386 lib32z1-dev lib32ncurses5-dev libssl-dev libxml2-dev libx11-dev libgl1-mesa-dev ) # 其他必要工具 other_tools=( rsync gawk ssh ccache doxygen xsltproc perl tcl tofrodos pigz expect ) # 合并所有依赖 all_deps=("${base_tools[@]}" "${build_tools[@]}" "${other_tools[@]}") echo "开始安装依赖..." sudo apt update sudo apt install -y "${all_deps[@]}" # 安装Python依赖 pip3 install --upgrade pip pip3 install pycryptodome pyyaml xlrd requests

给脚本执行权限并运行：

chmod +x install_deps.sh ./install_deps.sh

2.2 常见依赖问题解决

  • Python版本冲突：确保系统默认Python是3.8+，可以使用update-alternatives来管理。
  • Java版本问题：OpenHarmony需要Java 8，不要安装更高版本。
  • git-lfs问题：安装后需要运行git lfs install初始化。

3. 获取OpenHarmony源码

源码获取有两种方式，各有优缺点：

方式优点缺点适用场景
压缩包下载简单直接，一次性获取下载量大，更新麻烦网络稳定，需要完整代码
repo工具增量更新，灵活配置复杂，可能中断长期开发，需要频繁更新

3.1 使用repo工具获取源码

mkdir ~/openharmony && cd ~/openharmony # 安装repo工具 curl -s https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 > /usr/local/bin/repo chmod a+x /usr/local/bin/repo # 配置git git config --global user.name "YourName" git config --global user.email "your@email.com" git config --global credential.helper store # 初始化仓库（轻量版） repo init -u https://gitee.com/openharmony/manifest \ -b refs/tags/OpenHarmony-v4.1-Release \ -m chipsets/hispark_pegasus.xml \ -g ohos:mini # 同步代码（可能需要多次执行） repo sync -c repo forall -c 'git lfs pull'

注意：代码同步过程可能因网络问题中断，建议使用稳定的网络环境，必要时可以分段同步。

4. ESP32补丁与工具链配置

ESP32作为非官方支持的开发板，需要额外的补丁和工具链支持。

4.1 应用ESP32补丁

补丁通常包含以下部分：

  1. 设备树配置（device/board/esp32）
  2. 驱动支持（drivers/peripheral）
  3. 编译脚本修改（build/config）

将补丁文件复制到对应目录后，建议检查文件权限：

find device/board/esp32 -type f -exec chmod 644 {} \; find device/board/esp32 -type d -exec chmod 755 {} \;

4.2 安装交叉编译工具链

ESP32需要两套工具链：

  1. RISCV工具链（用于OpenHarmony）
  2. Xtensa工具链（用于ESP32）

RISCV工具链安装：

wget https://repo.huaweicloud.com/harmonyos/compiler/gcc_riscv32/7.3.0/linux/gcc_riscv32-linux-7.3.0.tar.gz tar -xzf gcc_riscv32-linux-7.3.0.tar.gz -C ~ echo 'export PATH=~/gcc_riscv32/bin:$PATH' >> ~/.bashrc source ~/.bashrc

Xtensa工具链安装：

mkdir -p ~/esp32_toolchain && cd ~/esp32_toolchain wget https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_4_0-esp-2021r2-linux-amd64.tar.gz sudo tar xvf xtensa-esp32-elf-gcc8_4_0-esp-2021r2-linux-amd64.tar.gz -C /opt/ echo 'export PATH=$PATH:/opt/xtensa-esp32-elf/bin' >> ~/.bashrc source ~/.bashrc

验证安装：

riscv32-unknown-elf-gcc -v xtensa-esp32-elf-gcc -v

5. 编译配置与问题解决

5.1 修改构建脚本

为了避免构建过程中的错误，需要修改build/hb/util/loader/load_ohos_build.py：

# 将所有的 raise OHOSException(...) # 替换为 print(...)

这个修改是为了绕过一些严格的检查，但要注意这可能会掩盖真正的问题，建议在开发完成后恢复原状。

5.2 使用hb工具编译

# 初始化hb环境 pip3 install --user build/hb echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc source ~/.bashrc # 配置和编译 cd ~/openharmony hb set # 选择esp32 hb build -f

5.3 常见编译错误解决

  1. 内存不足：增加swap空间或减少并行编译任务（-j参数）
  2. 文件权限问题：确保所有源码文件有正确的读写权限
  3. 网络超时：配置git和repo使用代理（如果需要）
  4. Python包冲突：使用虚拟环境隔离Python依赖

6. 开发环境优化建议

6.1 使用ccache加速编译

echo 'export USE_CCACHE=1' >> ~/.bashrc echo 'export CCACHE_DIR=~/.ccache' >> ~/.bashrc ccache -M 50G # 设置缓存大小 source ~/.bashrc

6.2 配置VS Code开发环境

推荐安装以下扩展：

  • C/C++
  • CMake Tools
  • Python
  • GitLens

配置.vscode/c_cpp_properties.json：

{ "configurations": [ { "name": "Linux", "includePath": [ "${workspaceFolder}/**", "/opt/xtensa-esp32-elf/**", "~/gcc_riscv32/**" ], "defines": [], "compilerPath": "/opt/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc", "cStandard": "c11", "cppStandard": "c++17", "intelliSenseMode": "linux-gcc-x64" } ], "version": 4 }

6.3 日常开发流程建议

  1. 代码修改前先创建分支：git checkout -b feature/xxx
  2. 定期同步上游代码：repo sync -c
  3. 增量编译：hb build（不带-f参数）
  4. 清理构建：rm -rf out（完全清理）

在完成环境搭建后，我发现最耗时的部分其实是各种工具链的下载和配置。建议将这些工具链打包备份，方便后续重用或在其他机器上快速部署。

http://www.jsqmd.com/news/653776/

相关文章：

  • MTK平台屏幕与TP驱动调试实战：LK、Kernel、DTS配置全解析
  • 智慧城市井盖智能巡检 智能城市道路巡检系统 井盖缺陷异常等识别 井盖缺失破损识别数据集 改进的yolo算法数据集第10311期
  • 软件散点图管理化的相关性分析
  • LayerDivider：3分钟将单张插画转换为分层PSD的智能解决方案
  • 收藏！小白程序员必看：从ReAct到Skills基座，硬核梳理Agent工程全貌
  • 从Codota到TabNine：AI代码补全插件在Eclipse与IDEA中的实战演进
  • Hypermesh二次开发实战：Tcl命令与*createmark高效应用
  • LDO vs DCDC：5个真实项目案例，告诉你什么时候该用谁（附选型清单）
  • 别再只玩ChatGPT了！手把手教你用LLaVA和MiniGPT-4搭建自己的多模态AI助手（附避坑指南）
  • 智慧城市之盲道图像分割数据集地铁盲道分割图像数据集智慧盲人路线指引数据集 yolov13 yolo26图像数据集第10258期 (1)
  • 避坑指南：华为设备GRE over IPSec配置中，ACL规则写错导致隧道不通的排查全过程
  • 优质白牦牛源头厂家2026推荐，口碑之选，目前有实力的白牦牛推荐分析技术领航，品质之选 - 品牌推荐师
  • 终极指南：如何用DriverStore Explorer轻松管理Windows驱动程序
  • TotalSegmentator：医学影像智能分割的开源解决方案与架构深度解析
  • STM32 SPI从机DMA避坑指南：没有IDLE中断，如何用定时器实现可靠的不定长数据接收？
  • Qwen3-Reranker-0.6B镜像免配置教程：开箱即用的语义匹配Web服务
  • 不只是最小系统：给STM32F429配上‘全家桶’（SDRAM、LCD、网络）的硬件设计避坑指南
  • 深入探索AMD Ryzen处理器：SMUDebugTool架构解析与实战应用
  • 你的PyTorch多卡训练效率低？可能是DataParallel的‘锅’！聊聊负载均衡那些事儿
  • 2026奇点大会AI客服机器人技术白皮书深度拆解（含未公开Benchmark对比：RAG延迟↓63%，情感误判率↓41.7%）
  • 大模型---Reflexion
  • 保姆级教程：手把手教你为小智AI Pro更换专属唤醒词和背景图（ESP32-S3实战）
  • EPLAN电气设计新手必看：结构标识符设置避坑指南（附实战截图）
  • 终极中文文案排版指北：从空格到标点的完整教程
  • 你的地图‘漂移’了吗？深入聊聊coord-convert库转换WGS84/GCJ-02时的误差与应对
  • FreeRTOS二值信号量实战：如何用STM32串口中断实现任务同步（附完整代码）
  • TSMaster HIL仿真避坑指南：如何正确监控与可视化车辆轮速、压力等关键信号？
  • Equalizer APO：解锁Windows音频系统级调校的三大应用场景
  • 从零构建中文NL2SQL数据集：基于GRPO强化学习微调Qwen3-8B，解锁300行复杂SQL生成
  • 避坑指南：升级Xcode 16后必做的CocoaPods兼容性检查（含.xcodeproj文件手动修复教程）