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

安装所有一切东西，

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

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

尽可能使用英文账户名，

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

正确示例

错误示例

1、项目前期问题

1.1.提前安装 node.js

这里建议 18 以上

Node.js — 下载 Node.js®

Node.js — 下载 Node.js® Node.js® is a free, open-source, cross-platform JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts. nodejs.org

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

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

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

1.2.Hyper-V 问题

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

问题现象

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

解决措施

1. 请先确认 CPU 型号是否支持虚拟化技术，如果不支持，则无法使用模拟器。

2. 请确保模拟器的运行环境符合要求。

3. 如果 CPU 支持虚拟化，打开控制面板 > 程序 > 程序与功能 > 启动或关闭 Windows 功能（对于 Windows 11 系统，需打开系统 > 可选功能，在相关设置中点击更多 Windows 功能），找到并勾选“Hyper-V”、“Windows 虚拟机监控程序平台”和“虚拟机平台”，点击确定并重启电脑。若勾选后启动模拟器仍提示错误，需以管理员权限打开命令行窗口，执行 `bcdedit /set hypervisorlaunchtype auto`，然后重启电脑。

   

4. 若勾选后启动模拟器仍然提示该错误，需要以管理员权限打开命令行窗口执行以下命令，并重启电脑。

   bcdedit /set hypervisorlaunchtype auto
   

5. 如果上述步骤无法解决问题，打开任务管理器，切换到“性能”选项卡。如果显示虚拟化已禁用或未开启，说明 BIOS 中虚拟化功能未开启。请根据计算机主板型号，进入 BIOS 设置界面，开启虚拟化功能。

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

2、运行时的问题

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

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

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

2.1.Android SDK 报错

‍

将安卓 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 Red
    exit 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，最关键是积极主动的问问相关领域的先行者大佬，（补：询问他人问题，要多看看提问的智慧， 大佬们也有着自己的事情，并不是专属一对一客服，请礼貌客气发问，并适当的等待）。