OpenHarmony与ArkUI-X的跨平台开发环境搭建细节版
安装所有一切东西，
尽可能安装在英文路径位置下,
尽可能使用默认路径位置，
尽可能使用英文账户名，
这样默认安装时，路径就符合上述要求，可以避免奇奇怪怪的问题
正确示例
错误示例
1、项目前期问题
1.1.提前安装node.js
这里建议18以上
Node.js — 下载 Node.js®
https://nodejs.org/zh-cn/download
建议下载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。
这一步之前，先参考开发环境搭建速通版，安装好两个IDE。
这一步之前，先参考开发环境搭建速通版，安装好两个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才行，因为我又试了其他版本的安卓模拟器都会白屏不报错，至此万分感谢白老师的帮助与指导。
3、总结
OpenHarmony与ArkUI-X的跨平台开发，安卓模拟器白屏问题，
Windows系统下，
DevEco Studio必须是5.1.0，对应的模拟器是5.1.0（API18）
Android Studio最新版，对应的模拟器是安卓16（API36），必须是默认的，带星号的版本。
在学习相关前言的技术时，总会遇到很多问题，可以多看看官方文档，各类社区文档，多问问AI，最关键是积极主动的问问相关领域的先行者大佬，（补：询问他人问题，要多看看提问的智慧， 大佬们也有着自己的事情，并不是专属一对一客服，请礼貌客气发问，并适当的等待）。