开源鸿蒙跨平台开发实战:从环境搭建到多终端部署的踩坑指南

本文记录了作者从零开始搭建开源鸿蒙开发环境并实现跨平台应用部署的全过程。文章详细梳理了开发过程中遇到的各种典型问题及解决方案，主要包括：开发环境搭建：SDK下载失败、环境变量配置、多设备驱动安装等问题 Git仓库管理：AtomGit配置、commit规范、分支管理实践工程创建与适配：跨平台工程创建、模块依赖配置、多设备参数设置等难点多终端运行验证：真机签名、开发板ABI匹配、模拟器启动等具体

wdracky

560人浏览 · 2026-01-13 15:37:15

wdracky · 2026-01-13 15:37:15 发布

## 标题

跑通了,终于跑通了!当看到自己的鸿蒙应用在真机、开发板、模拟器上正常运行的那一刻,之前的各种报错和环境问题都值了。这篇文章记录了我从零开始搭建开源鸿蒙开发环境,完成跨平台工程创建与部署的全过程,以及一路踩过的坑和解决方案。

📋 目录

前言:为什么写这篇文章
一、开发环境搭建:那些差点让我放弃的坑
二、Git与AtomGit仓库操作:从零到一的实践
三、工程创建与多终端适配:真正的挑战开始了
四、多终端运行验证:真机、开发板、模拟器全流程
五、代码提交规范:确保仓库可复现
六、总结与反思:新手的成长之路
- 6.1 最关键的几个点
- 6.2 给新手开发者的建议
参考资料

前言:为什么写这篇文章

作为一个刚接触开源鸿蒙开发的开发者,我按照官方文档和网上教程一步步搭建环境,却遇到了各种各样的问题:SDK下载失败、环境变量配置报错、真机无法连接、签名签名再签名……每个问题都卡了我半天甚至一整天。

当我好不容易把工程在手机、平板、DAYU200开发板和模拟器上都跑通,并把代码提交到AtomGit仓库后,我意识到,新手开发者需要的不是一份完美无瑕的教程,而是一份真实记录问题、提供解决方案的实战指南。

所以,我决定把这一路上的坑都写下来,希望能帮到和我一样的新手开发者。

一、开发环境搭建:那些差点让我放弃的坑

1.1 SDK下载失败的噩梦

按照要求,我已经提前安装好了VSCode、Git、Java和Android Studio,接下来就是安装DevEco Studio和OpenHarmony SDK。

打开DevEco Studio,按照指引配置SDK路径,一切看似顺利。但在下载SDK的时候,噩梦开始了:

Downloading OpenHarmony SDK...
Error: Install JS 3.0.0.1 failed. Error: Cause: An unknown error occurred.

问题排查:

刚开始我以为是网络问题,换了网络又试了几次,还是同样的错误。后来查了很多资料,才发现问题出在环境变量Path中有多余的引号或分号。

打开系统环境变量,检查Path变量,发现确实有几处格式不规范:

有的路径末尾有多余的;
有的路径被引号包裹但不规范
还有重复的路径配置

解决方案:

打开系统属性 → 环境变量
找到系统变量中的Path,点击编辑
把所有路径整理一遍,删除多余的;和",确保格式统一
重启DevEco Studio,重新下载SDK

这次终于成功了!这里给新手的建议:环境变量配置要特别小心,格式错误会导致各种莫名其妙的错误。

1.2 环境变量配置的正确姿势

SDK下载完成后,接下来是配置环境变量。很多教程只说"配置环境变量",但没说具体要配置什么,导致我走了不少弯路。

根据官方文档和我实际踩坑的经验,至少需要配置以下环境变量:

系统变量:

ANDROID_HOME = C:\Users\你的用户名\AppData\Local\Android\Sdk
Path添加: %ANDROID_HOME%\platform-tools;%ANDROID_HOME%\tools

用户变量:

JAVA_HOME = C:\Program Files\Java\jdk-17(或你安装的JDK路径)
Path添加: %JAVA_HOME%\bin

NODE_HOME = C:\Users\你的用户名\AppData\Local\HBuilder\plugins\nodejs
Path添加: %NODE_HOME%

特别提醒:

一定要配置JAVA_HOME,否则编译时会报"构建环境变量配置错误"
配置后必须重启电脑才能生效,只重启DevEco Studio是不够的
验证环境变量是否生效:打开CMD,输入java -version、adb -h等命令,如果能看到版本信息,说明配置成功

1.3 多设备调试驱动安装

为了支持真机、开发板、模拟器三类终端的调试,需要安装相应的驱动。

真机/平板驱动:

华为/荣耀手机通常自带驱动,连接电脑时自动安装
如果设备管理器显示黄色感叹号,需要手动安装驱动
建议使用官方提供的"华为手机助手"自动安装驱动

DAYU200开发板驱动:
DAYU200(RK3568开发板)需要单独安装串口驱动和网络驱动。

遇到的问题是:插上串口线后,设备管理器里能看到串口(COM8),但连接时一直失败。

解决方案:

下载RK3568专用USB驱动(可以从DAYU200官方文档获取)
正确安装后,设备管理器应该能看到"Prolific USB-to-Serial Comm Port"或类似标识
打开串口工具(如PuTTY),波特率设置为1500000(注意是1.5M,不是常规的115200)
复位开发板(按RESET按钮),在终端应该能看到启动日志

如果还是看不到启动日志,检查:

USB线是否正常(建议使用原装或质量好的数据线)
串口工具波特率是否设置正确
开发板是否正常上电(电源指示灯亮起)

二、Git与AtomGit仓库操作:从零到一的实践

2.1 Git配置与仓库创建

虽然我之前用过Git,但这次在使用AtomGit时还是遇到了一些问题。

初始配置:

git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"

仓库创建流程:

在AtomGit平台上创建公开仓库
配置仓库信息:
- README.md:编写项目说明,包括项目简介、技术栈、运行截图、贡献指南等
- .gitignore:使用HarmonyOS项目模板,排除不必要的文件(如node_modules、build目录等)
- License:选择合适的开源协议(如MIT、Apache 2.0)

2.2 Commit Message规范踩坑

刚开始我提交代码时,commit message写得很随意:

git commit -m "完成代码"

后来意识到这样不利于版本管理,于是学习并采用了规范的commit message格式:

推荐格式:

<type>(<scope>): <subject>

<body>

<footer>

type类型:

feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
test: 测试相关
chore: 构建/工具链相关

实际示例:

git commit -m "feat(project): 初始化OpenHarmony跨平台工程

- 完成基础UI界面搭建
- 配置多设备适配参数
- 添加基础权限声明

Closes #1"

2.3 分支管理规范

为了避免主分支被污染,我采用了Git Flow的简化版分支策略:

# 创建开发分支
git checkout -b dev

# 创建功能分支
git checkout -b feature/multi-device-support

# 开发完成后合并到dev
git checkout dev
git merge feature/multi-device-support

# dev稳定后合并到main
git checkout main
git merge dev

三、工程创建与多终端适配:真正的挑战开始了

3.1 跨平台工程创建的坑

使用DevEco Studio创建工程时,我遇到了第一个大坑。

按照教程,选择"OpenHarmony" → “Empty Ability” → 选择API 10,然后创建。看起来一切正常,但编译时却报错:

Error: Module 'entry' has no 'hvigorfile.ts' file

问题原因:

我创建的是Stage模型工程,但某些配置文件没有自动生成完整。

解决方案:

检查项目根目录是否有hvigor目录和hvigor-config.json5文件
如果没有,手动创建hvigorfile.ts:

export { hapTasks } from '@ohos/hvigor-ohos-plugin';

在hvigor-config.json5中配置插件:

{
  "dependencies": {
    "@ohos/hvigor-ohos-plugin": "4.0.4"
  }
}

点击"Sync Now"或重新Build,让插件生效

3.2 模块依赖配置问题

项目需要引用一些第三方库,配置依赖时又踩坑了。

在oh-package.json5中添加依赖:

{
  "dependencies": {
    "@ohos/lottie": "2.0.5"
  }
}

执行ohpm install时,提示找不到包。

问题原因:

OHPM源没有正确配置
包名或版本号写错

解决方案:

配置OHPM源:

ohpm config set registry https://repo.harmonyos.com/ohpm/

查看三方库中心仓(https://ohpm.openharmony.cn/)确认正确的包名和版本
如果还是不行,尝试清除缓存:

ohpm cache clean
ohpm install

3.3 多设备适配参数设置

跨平台开发的关键是多设备适配。在module.json5中,需要配置不同设备的支持情况。

我最初只配置了手机:

{
  "module": {
    "deviceTypes": ["default", "tablet"]
  }
}

但DAYU200开发板运行时,界面显示异常,分辨率不对。

解决方案:

在module.json5中明确支持设备类型:

{
  "module": {
    "deviceTypes": [
      "default",
      "phone",
      "tablet",
      "2in1"
    ]
  }
}

使用资源限定符,为不同设备准备不同资源:

resources/base/element/         // 通用资源
resources/phone/element/         // 手机专用
resources/tablet/element/       // 平板专用
resources/2in1/element/         // 二合一设备专用

使用百分比和弹性布局,而不是固定尺寸:

Flex({ direction: FlexDirection.Column }) {
  // 内容
}
.width('100%')
.height('100%')

3.4 权限声明的坑

项目需要使用网络、存储等权限,在module.json5中声明权限时又出了问题。

最初的配置:

{
  "requestPermissions": [
    { "name": "ohos.permission.INTERNET" }
  ]
}

运行时提示权限申请失败。

问题原因:

某些权限需要填写reason和usedScene,特别是user_grant级别的权限。

正确配置示例:

{
  "requestPermissions": [
    {
      "name": "ohos.permission.INTERNET",
      "reason": "$string:internet_permission_reason",
      "usedScene": {
        "abilities": ["EntryAbility"],
        "when": "inuse"
      }
    },
    {
      "name": "ohos.permission.GET_NETWORK_INFO",
      "reason": "$string:network_info_permission_reason",
      "usedScene": {
        "abilities": ["EntryAbility"],
        "when": "always"
      }
    }
  ]
}

同时要在string.json中声明对应的文案:

{
  "string": [
    {
      "name": "internet_permission_reason",
      "value": "应用需要访问网络以获取数据"
    },
    {
      "name": "network_info_permission_reason",
      "value": "应用需要获取网络信息以优化体验"
    }
  ]
}

四、多终端运行验证:真机、开发板、模拟器全流程

4.1 真机(手机/平板)调试:签名问题的地狱

这是我遇到的最大坑,没有之一!

一切准备就绪,将华为手机连接电脑,USB调试已开启,点击"运行",结果:

App Launch Install Failed: 
error: failed to install bundle. 
error: no signature file.

问题原因:

OpenHarmony应用必须签名才能在真机运行,默认生成的HAP包是未签名的。

解决方案一:自动签名

DevEco Studio提供了自动签名功能:

点击 File → Project Structure → Signing Configs
勾选"Automatically generate signature"
选择签名证书(CSR文件,如果没有会提示生成)
配置签名信息,点击"Apply"

注意: 自动签名只在同一个包名下有效。

解决方案二:手动签名(推荐用于生产环境)

生成密钥库(keystore)文件:

keytool -genkeypair -alias mykey -keyalg RSA -keysize 2048 -validity 3650 -keystore mykeystore.jks

在DevEco Studio中配置签名:
- File → Project Structure → Signing Configs
- 选择Manual Sign
- 填写keystore路径、密码、别名等信息
重新Build,生成签名后的HAP包

签名常见问题:

密码错误:一定要记清楚keystore密码和别名密码,丢了很难找回
证书过期:密钥有效期一般设置为3650天(10年)
多设备签名:如果要在多台电脑上开发,需要共享keystore文件,或者每台电脑分别生成签名

4.2 DAYU200开发板运行:ABI不匹配问题

好不容易解决了签名问题,在DAYU200开发板上运行又遇到新问题:

Error: Cannot load library: ABI mismatch

问题分析:

我使用的是Native C++项目,默认只生成了arm64-v8a架构的so库,但DAYU200开发板是armeabi-v7a架构。

排查步骤:

使用hdc命令查看设备的ABI类型:

hdc shell
getprop ro.product.cpu.abilist

输出显示:armeabi-v7a,armeabi

检查项目是否支持该ABI:

build/outputs/libs/

只看到arm64-v8a目录,没有armeabi-v7a

解决方案:

在entry/build-profile.json5中配置abiFilters:

{
  "apiType": "stageMode",
  "buildOption": {
    "externalNativeOptions": {
      "path": "./src/main/cpp/CMakeLists.txt",
      "arguments": "",
      "cppFlags": "",
      "abiFilters": [
        "armeabi-v7a",
        "arm64-v8a"
      ]
    }
  }
}

特别注意:

DevEco Studio Next Developer 5.0.3.200以上版本不再支持编译armeabi-v7a架构的so文件!如果遇到这个问题,有两个选择:

使用低版本的DevEco Studio
只用arm64-v8a架构,但这样DAYU200就无法运行了

我最终选择了方案1,使用DevEco Studio 5.0.2版本。

4.3 模拟器运行:启动失败问题

真机和开发板都解决了,模拟器又出问题。

创建Phone模拟器后,点击"运行",结果:

Emulator launch failed: Failed to allocate memory

问题原因:

模拟器启动需要较多内存,我的电脑内存(16GB)可能不够,或者虚拟化未开启。

解决方案:

检查BIOS是否开启虚拟化支持:
- 重启电脑,进入BIOS
- 找到Virtualization Technology选项,设置为Enabled
- 保存并重启
调整模拟器配置:
- 不要创建配置最高的设备
- 适当减少RAM大小(比如从6GB减到4GB)
- 磁盘空间给10GB就够
如果还是失败,检查:
- Windows虚拟化是否开启(在任务管理器→性能→CPU中查看)
- 杀毒软件是否拦截
- HAXM(硬件加速执行管理器)是否正确安装

五、代码提交规范:确保仓库可复现

5.1 合理的提交粒度

我刚开始犯了一个错误:把所有修改一次性提交,commit message写得很长。

后来调整策略,按照功能模块和文件类型分批提交:

# 提交1:初始化工程
git add oh-package.json5 hvigor-config.json5 build-profile.json5
git commit -m "feat(project): 初始化工程配置文件

- 配置模块依赖
- 设置多设备支持
- 添加Hvigor构建插件"

# 提交2:权限声明
git add entry/src/main/module.json5 entry/src/main/resources/base/element/string.json
git commit -m "feat(permission): 添加应用权限声明

- 添加网络权限
- 添加存储权限
- 配置权限使用场景"

# 提交3:UI界面
git add entry/src/main/ets/pages/Index.ets entry/src/main/resources/base/element/
git commit -m "feat(ui): 完成基础UI界面

- 实现首页布局
- 添加资源文件
- 适配多设备分辨率"

5.2 包含完整的工程文件

为了确保别人拉取代码后能直接复现,我在提交时特别注意包含了以下文件:

项目根目录/
├── oh-package.json5           # OHPM依赖配置
├── hvigor/
│   ├── hvigor-config.json5   # Hvigor构建配置
│   └── hvigorfile.ts         # 构建脚本
├── build-profile.json5        # 工程构建配置
├── AppScope/
│   ├── app.json5            # 应用级配置
│   └── resources/           # 应用级资源
├── entry/
│   ├── build-profile.json5   # 模块构建配置
│   ├── src/main/
│   │   ├── module.json5     # 模块配置(权限、设备类型等)
│   │   ├── ets/             # ArkTS源码
│   │   ├── resources/       # 资源文件
│   │   └── cpp/             # Native代码(如果有)
│   └── build/
│       └── outputs/
│           └── hap/
│               └── entry-debug-*.hap  # 编译产物(可选)
├── .gitignore               # Git忽略文件配置
├── README.md                # 项目说明
└── screenshots/             # 运行截图

5.3 调试日志的整理

为了方便排查问题,我在每次提交时都会附上关键的调试日志:

# 编译日志
git add logs/build.log
git commit -m "chore(log): 添加编译成功日志

编译时间: 2025-01-13 14:30
编译设备: Phone, Tablet, DAYU200
编译状态: SUCCESS"

# 运行日志
git add logs/run-phone.log
git commit -m "chore(log): 添加手机运行日志

运行设备: 华为Mate 50
API版本: 10
运行时间: 2025-01-13 15:00
功能验证: PASS"