目录

1. 前言

2. 项目状态

3. 运行时环境选择

4. NativeAOT 适配原理

4.1 底层兼容性

4.2 技术实现方案

5. 已知问题及解决方案

5.1 syscall 限制（已解决）

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

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

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

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

5.6 Marshal.GetDelegateForFunctionPointer 限制（已解决）

6. NativeAOT 源码修改指南

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 适配项目