.NET 在鸿蒙系统(HarmonyOS Next)上的适配探索与实践

目录

[1. 前言](#1. 前言)

[2. 项目状态](#2. 项目状态)

[3. 运行时环境选择](#3. 运行时环境选择)

[4. NativeAOT 适配原理](#4. NativeAOT 适配原理)

[4.1 底层兼容性](#4.1 底层兼容性)

[4.2 技术实现方案](#4.2 技术实现方案)

[5. 已知问题及解决方案](#5. 已知问题及解决方案)

[5.1 syscall 限制（已解决）](#5.1 syscall 限制（已解决）)

[5.2 mmap 申请虚拟内存过大（已解决）](#5.2 mmap 申请虚拟内存过大（已解决）)

[5.3 第三方库缺失问题（已解决）](#5.3 第三方库缺失问题（已解决）)

[5.4 ICU 初始化失败（已解决）](#5.4 ICU 初始化失败（已解决）)

[5.5 NativeAOT 跨平台编译（Windows平台已解决）](#5.5 NativeAOT 跨平台编译（Windows平台已解决）)

[5.6 Marshal.GetDelegateForFunctionPointer 限制（已解决）](#5.6 Marshal.GetDelegateForFunctionPointer 限制（已解决）)

[6. NativeAOT 源码修改指南](#6. NativeAOT 源码修改指南)

[7. 相关资源](#7. 相关资源)

---

1. 前言

在当前国产化操作系统发展浪潮下，适配鸿蒙系统已成为中国软件开发的重要趋势。作为微软推出的跨平台开发框架，.NET 凭借其卓越的性能和丰富的功能库，一直被视为最优秀的客户端开发语言之一。特别是对于 Avalonia 这样的跨平台 UI 框架，能够帮助开发者快速构建高质量的桌面应用程序。在去年的 .NET Conf China 大会上，我分享了关于将 Avalonia 移植到鸿蒙系统的初步探索。经过近一年的持续努力，项目又取得了一些突破性进展。本文将系统性地整理当前遇到的所有技术问题及解决方案，希望能为正在关注 .NET 鸿蒙适配的开发者提供有价值的参考。

2. 项目状态

目前，我们已经成功实现了 .NET 在 HarmonyOS Next 系统上的基础运行能力。具体而言：

• 基础运行时环境：已完成 .NET NativeAOT 运行时的适配工作
• 框架适配：Avalonia UI 框架可以在 HarmonyOS Next 真机上流畅运行
• 性能表现：经过优化后，应用程序启动速度和运行效率已达到可用水平

本文将重点探讨 .NET 运行时适配鸿蒙系统的关键技术细节，包括架构设计、问题定位和解决方案等。

3. 运行时环境选择

鸿蒙系统从 5.0.0(12) 版本开始引入了严格的安全限制：

1. 内存执行限制：禁止匿名内存申请可执行权限
2. JIT 限制：除系统内置的 JavaScript 引擎外，其他虚拟机均不能使用 JIT 编译功能

这些限制给 .NET 运行时的适配带来了巨大挑战：

• CoreCLR 不可用：由于依赖 JIT 编译，无法接入鸿蒙系统
• Mono 方案被弃用：虽然最新版 Mono 支持解释执行，但性能问题使其不适合生产环境
• 最终选择：NativeAOT 运行时成为唯一可行的方案，通过提前编译(AOT)生成原生代码

4. NativeAOT 适配原理

NativeAOT 能够在鸿蒙系统上运行的关键在于鸿蒙的底层兼容性设计：

4.1 底层兼容性

• libc 兼容：鸿蒙系统兼容 musl libc 的 Linux 动态库(.so)
• RID 支持：.NET 原生支持 linux-musl-arm64/linux-musl-x64 运行时标识符(RID)

4.2 技术实现方案

1. .NET 程序编译：

   • 将 .NET 代码编译为原生 Linux 动态库(.so)
   • 导出必要的入口函数供鸿蒙调用

2. 鸿蒙原生集成：

   // 加载 .NET 生成的动态库
   void* handle = dlopen("libdotnetapp.so", RTLD_LAZY);
   
   // 获取入口函数
   typedef int (*EntryPoint)(int argc, char** argv);
   EntryPoint entry = (EntryPoint)dlsym(handle, "DotNetMain");
   
   // 调用 .NET 入口函数
   entry(argc, argv);

3. 双向交互机制：

   • .NET 调用鸿蒙 API ：
     • 通过 P/Invoke 调用鸿蒙 NDK 提供的原生接口
     • 对于 ArkUI 的 TypeScript API，通过 NDK 中的 napi 机制进行桥接

4. 实际项目参考：

   • Avalonia 移植项目：OpenHarmony.Avalonia
   • 该项目完整展示了如何将复杂的 UI 框架适配到鸿蒙系统

5. 已知问题及解决方案

5.1 syscall 限制（已解决）

问题描述：

• 鸿蒙使用 seccomp 严格限制系统调用
• .NET 运行时初始化时会检查 NUMA 支持，调用 __NR_get_mempolicy 系统调用
• 该调用不在鸿蒙的 seccomp 白名单中，导致进程直接被终止

技术细节：

• 鸿蒙 seccomp 白名单：app.seccomp.policy
• 类似限制在 Android 也存在，但 .NET 对 Android 有特殊处理

解决方案： 修改 NativeAOT 源代码，将 NUMA 相关函数替换为空实现：

// 修改 numa.c
void numa_init() { /* 空实现 */ }
int numa_available() { return -1; } // 表示不支持

5.2 mmap 申请虚拟内存过大（已解决）

问题现象：

• GC 初始化时尝试申请 256GB 虚拟内存
• 超出鸿蒙系统限制，导致 mmap 返回 Out Of Memory 错误

解决方案：

方案1：环境变量控制

export DOTNET_GCHeapHardLimit=180000000000 # 限制堆大小为约180GB

方案2：源码级修改

• 在构建配置中禁用 USE_REGIONS 宏
• 修改 gcenv.h 文件：

#define USE_REGIONS 0

5.3 第三方库缺失问题（已解决）

问题范围：

• ICU（国际化组件）
• OpenSSL（加密库）
• 其他基础依赖库

解决方案：

方案1：从 Alpine Linux 移植

• Alpine 使用 musl libc，与鸿蒙兼容
• 阿里云镜像地址：
  • ARM64: https://mirrors.aliyun.com/alpine/edge/main/aarch64/
  • x86_64: https://mirrors.aliyun.com/alpine/edge/main/x86_64/

方案2：源码编译 对于有 CMake 支持的项目，使用鸿蒙工具链交叉编译：

cmake -DCMAKE_TOOLCHAIN_FILE=OHOS_TOOLCHAIN.cmake ..
make

5.4 ICU 初始化失败（已解决）

问题原因：

• 鸿蒙系统的 ICU 数据文件路径特殊
• 库版本不匹配

解决方案：

1.设置环境变量：

setenv("ICU_DATA", "/system/usr/ohos_icu", 1);

2.确保使用 libICU 72 版本：

ldd libicuuc.so.72

如果该库有cmake项目，则可以通过鸿蒙的CMake工具链编译。

5.5 NativeAOT 跨平台编译（Windows平台已解决）

问题描述：

• NativeAOT 默认不支持跨平台编译
• 开发效率受限于必须在 Linux 环境下构建

解决方案 ： 集成 PublishAotCross 项目：

1. 在 Windows 上编写代码
2. 通过自动化工具链完成 Linux 环境下的交叉编译
3. 获取最终的可执行文件

5.6 Marshal.GetDelegateForFunctionPointer 限制（已解决）

问题本质：

• 该函数依赖动态生成汇编代码
• 违反鸿蒙的 JIT 限制

替代方案： 使用 C# 9.0 引入的函数指针特性：

delegate* unmanaged<int, void> funcPtr = ...;
funcPtr(123);

6. NativeAOT 源码修改指南

若要修改 NativeAOT 源代码并重新构建，请按以下步骤操作：

1. 获取源码：

   git clone https://github.com/dotnet/runtime.git

2. 应用补丁：

   • 修改 numa.c、gcenv.h 等相关文件

3. 构建命令：

   ./build.sh --subset clr.aot --configuration Release -arch arm64 --cross

4. 替换 NuGet 包：

   • 构建产物位于 runtime/artifacts/bin/coreclr/linux.arm64.Release/aotsdk

   • 复制到 NuGet 缓存目录，如：

     C:\Users\<用户名>\.nuget\packages\runtime.linux-musl-arm64.microsoft.dotnet.ilcompiler\<版本>\sdk

7. 相关资源

1. GitHub Issues 跟踪：

   • Runtime #110074
   • Runtime #111649

2. 项目仓库：

   • OpenHarmony-NET 组织
   • Avalonia 适配项目