目錄
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) 版本開始引入了嚴格的安全限制：
- 內存執行限制：禁止匿名內存申請可執行權限
- 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 技術實現方案
-
.NET 程序編譯：
- 將 .NET 代碼編譯為原生 Linux 動態庫(.so)
- 導出必要的入口函數供鴻蒙調用
-
鴻蒙原生集成：
// 加載 .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); -
雙向交互機制：
- .NET 調用鴻蒙 API：
- 通過 P/Invoke 調用鴻蒙 NDK 提供的原生接口
- 對于 ArkUI 的 TypeScript API，通過 NDK 中的 napi 機制進行橋接
- .NET 調用鴻蒙 API：
-
實際項目參考：
- 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 項目：
- 在 Windows 上編寫代碼
- 通過自動化工具鏈完成 Linux 環境下的交叉編譯
- 獲取最終的可執行文件
5.6 Marshal.GetDelegateForFunctionPointer 限制（已解決）
問題本質：
- 該函數依賴動態生成匯編代碼
- 違反鴻蒙的 JIT 限制
替代方案： 使用 C# 9.0 引入的函數指針特性：
delegate* unmanaged<int, void> funcPtr = ...;
funcPtr(123);
6. NativeAOT 源碼修改指南
若要修改 NativeAOT 源代碼并重新構建，請按以下步驟操作：
-
獲取源碼：
git clone https://github.com/dotnet/runtime.git -
應用補丁：
- 修改
numa.c、gcenv.h等相關文件
- 修改
-
構建命令：
./build.sh --subset clr.aot --configuration Release -arch arm64 --cross -
替換 NuGet 包：
- 構建產物位于
runtime/artifacts/bin/coreclr/linux.arm64.Release/aotsdk - 復制到 NuGet 緩存目錄，如：
C:\Users\<用戶名>\.nuget\packages\runtime.linux-musl-arm64.microsoft.dotnet.ilcompiler\<版本>\sdk
- 構建產物位于
7. 相關資源
-
GitHub Issues 跟蹤：
- Runtime #110074
- Runtime #111649
-
項目倉庫：
- OpenHarmony-NET 組織
- Avalonia 適配項目
