OpenHarmony与ArkUI-X的跨平台开发环境搭建细节版

news/2025/11/26 21:34:16/文章来源:https://www.cnblogs.com/EAWA/p/19274702/detailed-version-of-crossplatform-development-environment-construction-between-openharmony-1fnovj

OpenHarmony与ArkUI-X的跨平台开发环境搭建细节版

安装所有一切东西，

尽可能安装在英文路径位置下,

尽可能使用默认路径位置，

尽可能使用英文账户名，

2025-11-26_174040

这样默认安装时，路径就符合上述要求，可以避免奇奇怪怪的问题

正确示例

2025-11-26_173825

错误示例

2025-11-26_173714

1、项目前期问题

1.1.提前安装node.js

这里建议18以上

Node.js — 下载 Node.js®

https://nodejs.org/zh-cn/download

2025-11-26_171627

建议下载LTS版本，（其他需要安装的也可以选LTS版本，但要注意开发环境所需版本）

LTS 是 Long-Term Support 的缩写，中文意思是 “长期支持” 或 “长期维护” 。

一个软件的 LTS版本 指的是一个会获得长期、稳定的技术支持、错误修复和安全更新的特定发布版本。

1.2.Hyper-V问题

需要在Windows电脑上启动模拟器，提示未开启Hyper-V

问题现象

启动模拟器时，如果未开启Hyper-V，或在虚拟环境中使用模拟器，会弹窗提示“Hyper-V not enabled”。

解决措施

请先确认CPU型号是否支持虚拟化技术，如果不支持，则无法使用模拟器。
请确保模拟器的运行环境符合要求。
如果CPU支持虚拟化，打开控制面板 > 程序 > 程序与功能 > 启动或关闭Windows功能（对于Windows 11系统，需打开系统 > 可选功能，在相关设置中点击更多Windows功能），找到并勾选“Hyper-V”、“Windows虚拟机监控程序平台”和“虚拟机平台”，点击确定并重启电脑。若勾选后启动模拟器仍提示错误，需以管理员权限打开命令行窗口，执行 `bcdedit /set hypervisorlaunchtype auto`，然后重启电脑。
若勾选后启动模拟器仍然提示该错误，需要以管理员权限打开命令行窗口执行以下命令，并重启电脑。
```
bcdedit /set hypervisorlaunchtype auto
```
如果上述步骤无法解决问题，打开任务管理器，切换到“性能”选项卡。如果显示虚拟化已禁用或未开启，说明BIOS中虚拟化功能未开启。请根据计算机主板型号，进入 BIOS 设置界面，开启虚拟化功能。

如果安装和开启Hyper-V的过程遇到其他问题，请根据系统版本查阅相关文档。更多关于Hyper-V安装请参考在Windows上安装Hyper-V和Hyper-V系统要求。

2、运行时的问题

这一步之前，先参考开发环境搭建速通版，安装好两个IDE。

2.1.Android SDK报错

‍

ANDROID_HOME not set. Set the environment variable. Then, close DevEco Studio and open it again.

将安卓AndroidSDK配置到环境变量
用powerShell执行下列命令

# 首先确定 Android SDK 路径
$sdkPath = "$env:LOCALAPPDATA\Android\Sdk"# 如果上述路径不存在，请手动指定
if (-not (Test-Path $sdkPath)) {$sdkPath = Read-Host "请输入 Android SDK 完整路径 (例如: C:\Android\Sdk)"
}# 验证路径是否存在
if (-not (Test-Path $sdkPath)) {Write-Host "错误: 指定的路径不存在!" -ForegroundColor Redexit 1
}Write-Host "设置 ANDROID_HOME 为: $sdkPath" -ForegroundColor Green# 设置系统级 ANDROID_HOME 环境变量
[Environment]::SetEnvironmentVariable("ANDROID_HOME", $sdkPath, "Machine")# 获取当前系统 PATH
$currentSystemPath = [Environment]::GetEnvironmentVariable("Path", "Machine")# 需要添加到 PATH 的目录
$pathsToAdd = @("$sdkPath\platform-tools","$sdkPath\tools","$sdkPath\emulator"  # 可选，用于 Android 模拟器
)# 添加新路径到系统 PATH（如果尚未存在）
foreach ($newPath in $pathsToAdd) {if ($currentSystemPath -notmatch [regex]::Escape($newPath)) {$currentSystemPath += ";$newPath"Write-Host "已添加到 PATH: $newPath" -ForegroundColor Yellow} else {Write-Host "PATH 中已存在: $newPath" -ForegroundColor Gray}
}# 更新系统 PATH
[Environment]::SetEnvironmentVariable("Path", $currentSystemPath, "Machine")Write-Host "系统级环境变量设置完成!" -ForegroundColor Green

# 设置用户级 ANDROID_HOME
[Environment]::SetEnvironmentVariable("ANDROID_HOME", $sdkPath, "User")# 更新用户级 PATH
$currentUserPath = [Environment]::GetEnvironmentVariable("Path", "User")
foreach ($newPath in $pathsToAdd) {if ($currentUserPath -notmatch [regex]::Escape($newPath)) {$currentUserPath += ";$newPath"}
}
[Environment]::SetEnvironmentVariable("Path", $currentUserPath, "User")Write-Host "用户级环境变量设置完成!" -ForegroundColor Green

2.2.下载HarmonyOS SDK时提示网络连接错误

问题现象

网络连接正常，但下载HarmonyOS SDK时提示网络连接错误。

解决措施

由于使用的PC系统语言为英文且区域码为US，可能导致问题。请按照以下步骤将区域码修改为CN，在修改前请确保已关闭DevEco Studio。

在C:\Users\_username_\AppData\Roaming\Huawei\DevEcoStudio4.1\options路径下（MacOS 路径为/Users/_username_/Library/Application Support/Huawei/DevEcoStudio4.1/options），打开country.region.xml文件，将countryregion name修改为“CN”。

<application><component name="CountryRegionSetting"><countryregion name="CN"/></component>
</application>

‍

2.3.DevEco Studio无法打开

问题现象

在Windows 10和Windows 11中，修改字符编码后，安装在中文目录下的DevEco Studio无法打开，报错“Error launching...”。

解决措施

请在英文目录下重新安装DevEco Studio。

‍

2.4.DevEco Studio 6.0.0 Beta1 及以上版本DevEco Studio ARKUI-X工程构建app报错

更新时间: 2025-11-21 15:15

问题现象

构建app报错：“Could not open settings generic class cache for settings file”

常见错误场景

当前工程为使用低于DevEco Studio 6.0.0 Beta1 版本的DevEco Studio创建的。

问题原因

DevEco Studio 6.0.0 Beta1版本DevEco Studio内置的java版本为21，当前gradle的版本低于java21配套的版本。

解决措施：

方式一：升级gradle版本修改gradle-wrapper.properties中的distributionUrl，升级为8.4版本。
```
distributionUrl=https\://repo.huaweicloud.com/gradle/gradle-8.4-bin.zip
```
方式二：指定使用java17如果本地有jdk17，可以在gradle.properties中通过org.gradle.java.home变量指定使用java17。

2.5.我主要遇到的无法解决的问题

大多数问题都可以问Ai进行解决，在自学过程中，要善于询问ai，可以看看提问的智慧，问ai也要说清楚你在干什么，大体就是说，在什么样的情况下，在使用什么做什么，遇到了什么样的问题

个人在环境搭建中遇到的问题是，DevEoc Studio端的虚拟机正常运行，没有报错，Android Studio的虚拟机能运行没有报错

‍

折腾好些时间，就一直是这样，左边鸿蒙的IDE正常显示，右边安卓的IDE就是一片白，ai问了解决不了，模拟器也换了，还是这样，试过把各个软件版本降低API也降低，还是这样

然后看了ArkUI-X的官方文档，配套关系如下

鸿蒙端用的是API18，然后看到安卓适配的是安卓8，API26，安卓模拟器也使用了安卓8，API26，然后会提示架构不合，我就升级到了安卓11，架构符合了，就一直白屏

在Android Studio的模拟器里，安卓10以下都不兼容，又怕安卓版本太高不兼容，所以使用了安卓11，没有使用最新的安卓16版本，

在安卓模拟器版本为11的情况下，在试鸿蒙端的API从10到20都试过了，也是白屏，在各个官方社区，都找不到问题，问了ai也解决不了，然后求助于创新乐知的白晓明老师，在白老师的帮助下排除了诸多问题的可能性，然后是Windows端的DevEco Studio6.0.0以上的版本有问题，应该是hvigor构建工具的问题，因为Mac端最新的DevEco Studio6.0.0正常运行，

所以Windows端使用DevEco Studio5.1.0版本，并且安卓端模拟器也要使用最新的安卓16，API36才行，因为我又试了其他版本的安卓模拟器都会白屏不报错，至此万分感谢白老师的帮助与指导。
2025-11-26_180317