许可优化
许可优化
产品
产品
解决方案
解决方案
服务支持
服务支持
关于
关于
软件库
当前位置:服务支持 >  软件文章 >  Unity iOS交互踩坑记录,苹果平台开发避坑经验

Unity iOS交互踩坑记录,苹果平台开发避坑经验

阅读数 23
点赞 0
article_banner


Unity iOS 交互踩坑:把 __Internal 写在热更程序集里,必然翻车

先给结论,一句话级别的根因:[DllImport("__Internal")] 必须放在 AOT(基础)程序集里,热更程序集里写的 DllImport 在 iOS 上永远是 DllNotFoundException——你贴的那个报错就是这条规则的典型症状。这个坑不是奇技淫巧踩出来的,是 HybridCLR 在 iOS 上的架构性限制,从 v9.0.0 开始官方干脆把“热更代码定义 extern 函数”这个特性整个移除了,就是因为它在 iOS 上根本跑不通。

下面把这件事拆开讲:为什么会报这个错、iOS 的 __Internal 机制是怎么回事、HybridCLR 在这里做了什么妥协、以及标准解法和几条延伸的坑。

一、先把那个报错读明白


DllNotFoundException: Unable to load DLL '__Internal'. 
Tried: '/__Internal' (no such file)

很多人第一反应是“我没把 .mm 文件拖进去”或者“Xcode 配置错了”,于是去翻 Plugins 设置、翻 Xcode 的 Build Phases,结果什么都没发现——因为这不是文件没打进去,而是这个调用压根不应该发生。

__Internal 不是文件名,是一个魔法关键字,它的含义是“去主可执行文件里找符号”。iOS 上所有 C/C++/Objective-C 代码都会被静态链接进 UnityAppController 所在的那个主二进制里,没有真正的动态库可加载,所以 Unity 官方文档明确说:iOS 插件用 __Internal 作为库名,表示插件代码和 Unity 运行时一起编译进了同一个二进制。

而 HybridCLR 的热更 DLL 是运行时从服务器下载、由解释器加载执行的 IL 字节码,它根本不参与主包的 AOT 编译,自然也不在主二进制里。当热更程序集里写着一个 [DllImport("__Internal")] 的 extern 函数被调用时,HybridCLR 只能去运行时查找符号——但 iOS 上的可执行文件根本没有可被 dlopen 的动态库符号表,于是 dlopen 直接返回 no such file,那个长串报错就来了。

一句话总结:__Internal 是个指向主二进制的引用,热更程序集不在主二进制里,所以这个引用永远悬空。 不是配置问题,是架构上就写不通。

二、HybridCLR 官方立场:这事已经写进了“不支持清单”

打开 HybridCLR 的“不支持的特性”文档,第一条就是:

不支持在热更新代码中定义 extern 函数([DllImport])。该特性曾在 v8.0.0-v8.15.0 期间可用,自 v9.0.0 版本起已移除。请将 extern 函数定义在 AOT 程序集中。hybridclr.cn

再看 PInvoke 支持文档里的平台支持表:热更代码里定义 extern 函数这个特性在 Windows/Linux/Mac/Android 都能用(这些平台可以运行时 dlopen 找符号),唯独 iOS 和 WebGL 两栏是空。

为什么 v8 那段时间看似能用、v9 又被砍掉?因为那个“支持”依赖运行时在动态链接库里查找符号,前提是平台有可加载的动态库。Windows 上你能真的 dlopen 一个 .dll,Android 上能 dlopen 一个 .so,所以热更程序集里的 DllImport 在那些平台能跑通。iOS 是纯静态链接,没东西可 dlopen,所以这个特性在 iOS 上从始至终就是个谎言,HybridCLR 官方最终在 v9 干脆移除了——在 iOS 上跑只会抛 ExecutionEngineException: not support extern method: xxxx。

你项目里报的是 DllNotFoundException 而不是 ExecutionEngineException,说明你们用的可能是 v8.x 版本(v8 在 iOS 上尝试 dlopen 失败就报这个错),或者版本更老。但不管哪个版本,结论一致:这条路在 iOS 上就是不通的。

三、iOS 原生交互的底层机制:为什么 __Internal 必须在 AOT 里

要真正理解这个坑,得回到 IL2CPP 的编译流程。Unity 在 iOS 上的工作流是:

  1. C# 源代码 → IL2CPP 转换成 C++ 源码
  2. C++ 源码和你 Plugins/iOS 目录下的 .mm 文件一起被编译
  3. 链接器把它们全部链接进一个主可执行文件(你 iPhone 上那个 App)

这意味着:只有参与了第 2、3 步的代码,才能和 .mm 文件里的符号“面对面”。主工程(AOT 程序集)的代码走完了这条完整链路,所以主工程里的 [DllImport("__Internal")] 在 AOT 编译阶段就被识别成了“指向本二进制内部某个符号的调用”,IL2CPP 会为它生成完整的 marshal 代码,运行时直接函数指针调用,根本不走 dlopen。hybridclr.cn

热更程序集的 DLL 是运行时下载的 IL 字节码,它压根没参与过那两次编译,所以它里面的 DllImport 只能被当成一个“运行时再去查动态库”的请求——而 iOS 没有动态库可查,于是报错。

补充元数据机制(HybridCLR 给 AOT 补泛型元数据的那套)也救不了这个场景。补充元数据解决的是“AOT 里已有的类型在热更侧能用”,它不解决“热更侧调用一个 AOT 里根本不存在的 native 符号”——因为主包构建时那个符号对应的桥接函数就没生成,运行时无路可走。

四、标准解法:三层架构 + 在 AOT 程序集里放桥接层

HybridCLR 文档里推荐的唯一受支持的 PInvoke 用法是这样的:


┌─────────────────────────────────────────┐
│  热更程序集 (下载 DLL)                     │
│  调用 AOT 里的 NativeApi 静态类            │
└────────────────┬────────────────────────┘
                 │ C# 调用 C#
┌────────────────▼────────────────────────┐
│  AOT 基础程序集 (打进主包)                 │
│  集中放所有 [DllImport("__Internal")]      │
└────────────────┬────────────────────────┘
                 │ PInvoke
┌────────────────▼────────────────────────┐
│  iOS 原生层 (.mm / .h in Plugins/iOS)    │
└─────────────────────────────────────────┘


AOT 程序集这边(打进主包,比如新建一个 NativeBridge.asmdef):


// NativeBridge.cs —— 在 AOT 程序集中
using System.Runtime.InteropServices;

public static class NativeApi
{
    [DllImport("__Internal")]
    private static extern void _showBannerAd(string adUnitId);

    [DllImport("__Internal")]
    private static extern int _getDeviceId();

    [DllImport("__Internal")]
    private static extern void _requestPermission(int type);

    // 给热更层暴露的公共接口
    public static void ShowBannerAd(string adUnitId) => _showBannerAd(adUnitId);
    public static int GetDeviceId() => _getDeviceId();
    public static void RequestPermission(int type) => _requestPermission(type);
}


.mm 这边(Plugins/iOS/):


// NativeBridge.mm
extern "C" {
    void _showBannerAd(const char* adUnitId) {
        NSString *unitId = [NSString stringWithUTF8String:adUnitId];
        [[AdManager shared] showBanner:unitId];
    }
    int _getDeviceId() {
        return [[DeviceManager shared] getId];
    }
    void _requestPermission(int type) {
        [[PermissionManager shared] request:type];
    }
}


热更程序集这边:


// HotUpdateCode.cs —— 在热更程序集中
public class LoginManager
{
    public void StartLogin()
    {
        // 直接调用 AOT 的静态方法,编译期就能解析到 AOT 程序集
        NativeApi.RequestPermission(0);
        string deviceId = NativeApi.GetDeviceId().ToString();
        // ... 走登录流程
    }
}


几个细节必须做对:

  • AOT 程序集要用 asmdef 明确划分,热更程序集的 asmdef 引用它,这样编译期就能解析到 NativeApi,运行时是通过 AOT 已编译好的方法调用 native,不走任何动态查找。
  • Editor 平台用 Mock 实现,否则在编辑器里跑会直接 DllNotFoundException(Editor 走 Mono,没有主二进制可找)。常见做法:
public static class NativeApi
{
#if UNITY_IOS && !UNITY_EDITOR
    [DllImport("__Internal")]
    private static extern void _showBannerAd(string adUnitId);
    public static void ShowBannerAd(string adUnitId) => _showBannerAd(adUnitId);
#else
    public static void ShowBannerAd(string adUnitId) 
    {
        Debug.Log($"[Mock] ShowBannerAd({adUnitId})");
    }
#endif
}


  • 接口签名要提前规划死。AOT 里那些 DllImport 函数没法热更——它们是打进主包的,发布之后加新签名就要重新提审。HybridCLR 文档专门强调:“如果 native 函数签名在发布主包时还不确定,需要在 AOT 中预先定义好这些声明——这部分无法热更新,请提前规划好 native 接口。”hybridclr.cn 实际工程里推荐的做法是把 AOT 桥接层做成泛化的通用接口,比如 void CallNative(string method, string jsonArgs),热更侧传 JSON 字符串过去,原生侧自己解析,这样后续加新功能就不需要动 AOT 层。

五、延伸坑一:link.xml 和代码裁剪

这是 iOS 真机上和 DllNotFoundException 一起出现频率最高的另一个坑,顺手一起讲了。

iOS 用 IL2CPP 编译时会有 Code Stripping,把没被主工程直接引用的类型和方法全部裁掉。热更代码里用到的 AOT 类型,如果主工程没显式引用,就被裁掉了,运行时报 TypeLoadException 或 MissingMethodException。

解决方案两层:

  1. link.xml 兜底:com.code-philosophy.hybridclr 包里有 HybridCLR/Generate/LinkXml 菜单命令,能一键扫描热更代码里引用的 AOT 类型并生成 link.xml。
  2. 主工程显式引用:link.xml 不是万能的,主工程没有任何引用时,link.xml 即使写了也可能裁不干净。最稳的做法是在主工程写一个 DisStripCode.cs,把热更侧会用到的关键类、关键方法显式调用一遍(哪怕调用的是空方法):
// DisStripCode.cs —— AOT 主工程里
static class DisStripCode
{
    [Preserve]
    static void Preserve()
    {
        // 显式引用,防止被裁剪
        var _ = typeof(System.Net.Http.HttpClient);
        var __ = typeof(UnityEngine.Rendering.Universal.UniversalRenderPipelineAsset);
        NativeApi.GetDeviceId(); // 即使暂时不用也调用一下
    }
}


一个特别容易踩的细分坑:iOS 特定的原生类型(相机、WebCam、动画、物理之类)优先用 AOT 显式引用验证,不要只依赖热更侧反射去访问,因为裁剪优先级和反射查找优先级有时候会互相打架,真机上莫名其妙就是找不到类型。

六、延伸坑二:反向回调(Native → C#)

桥接另一头——iOS 原生回调 C#——也有讲究,两种方式:

UnitySendMessage(简单但有局限):


// Objective-C 侧
UnitySendMessage("NativeCallbackReceiver", "OnLoginResult", "success|token=abc");
// C# 侧,挂在名为 NativeCallbackReceiver 的 GameObject 上
public class NativeCallbackReceiver : MonoBehaviour
{
    public void OnLoginResult(string message) { /* 处理 */ }
}

局限:签名固定为 void MethodName(string)、异步延迟一帧、GameObject 名字冲突会出错。

委托回调(更灵活,注意 GC):


// C# 侧
delegate void NativeCallback(string message);

[MonoPInvokeCallback(typeof(NativeCallback))]
static void OnNativeCallback(string message) { /* 处理 */ }

[DllImport("__Internal")]
static extern void _registerCallback(NativeCallback callback);

// 初始化时注册
static void Setup()
{
    _registerCallback(OnNativeCallback);
}
// Objective-C 侧
static NativeCallback g_callback;
void _registerCallback(NativeCallback cb) { g_callback = cb; }
// 后续调用
g_callback(@"hello");

委托方式更灵活,但要注意C# 侧的 delegate 引用必须保持不被 GC——通常用 static 字段持有,否则 delegate 被 GC 后原生侧持有的函数指针就是野指针,必崩。

另外回调线程问题:原生回调经常不在 Unity 主线程(比如网络回调、GCD 队列),而 Unity API 只能在主线程调,正确做法是桥接层把回调投递到主线程队列统一派发,而不是在回调里直接操作 Unity 对象。github.io

七、跨平台对照:这个坑只在 iOS 上有吗?

严格说,热更程序集里写 DllImport 这个坏习惯,在不同平台表现不同,这是它特别有迷惑性的原因:


平台热更程序集里 DllImport “__Internal”热更程序集里 DllImport “XXX”(动态库)
Unity Editor报错(Editor 没有 __Internal)可能能用
Windows 真机报错可能能用(能 dlopen)
Android 真机报错可能能用(.so 可动态加载)
iOS 真机必然报错(本文场景)必然报错
WebGL报错报错

注意 Android 那一格的“可能能用”——这正是这个坑最迷惑人的地方。项目如果先上 Android,热更程序集里写 [DllImport("someplugin")] 调一个 .so 的方法,Android 真机上能跑通,团队就以为这个写法没问题;等切到 iOS,忽然满屏 DllNotFoundException,大家就开始怀疑 Xcode 配置、怀疑 .mm 没打进去,实际上是写法从第一天就错,只是 Android 兜住了而已。

所以一条铁律:所有 PInvoke 声明,不管哪个平台,都收口到 AOT 程序集的 NativeApi 静态类里,热更层只调这个静态类的方法。这条规则在 Android 上多此一举,在 iOS 上是生死线,统一执行能省掉一半的跨平台排错时间。

八、v9.0.0 迁移清单

如果你项目还在 HybridCLR v8.x,并且热更程序集里有 DllImport,升级 v9 后会直接抛 ExecutionEngineException: not support extern method: xxxx。官方给的迁移步骤就是本文第三节的做法:

  1. 找出热更程序集中所有带 [DllImport] 的 extern 函数声明;
  2. 把这些声明移到 AOT 程序集的一个静态类里(比如 NativeApi);
  3. 热更代码改为调用该 AOT 类的方法;
  4. 重新走一遍 HybridCLR/Generate/All,重新打包主包。

如果 native 接口在发布主包时还不确定,在 AOT 中预留——这是唯一办法,AOT 层的签名没法热更。

商业版的 DHE(差分混合执行)技术确实支持在 DHE 程序集中直接定义 extern 函数,但那是付费方案,开源版老老实实按“DllImport 全部放 AOT”来就行。

核心一句话记住就够:iOS 的 native 符号只对参与了 AOT 编译的代码可见,热更程序集永远不参与 AOT 编译,所以所有 DllImport 必须放 AOT,热更侧只通过 AOT 的静态类间接调用。 这条规则建立起来后,剩下的问题基本就是 link.xml 裁剪、回调线程、Editor Mock 这类工程化细节,按本文的清单排查就行。



免责声明:本文系网络转载或改编,未找到原创作者,版权归原作者所有。如涉及版权,请联系删

相关文章
技术文档
QR Code
微信扫一扫,欢迎咨询~
customer

online

联系我们
武汉格发信息技术有限公司
湖北省武汉市经开区科技园西路6号103孵化器
电话:155-2731-8020 座机:027-59821821
邮件:tanzw@gofarlic.com
Copyright © 2023 Gofarsoft Co.,Ltd. 保留所有权利
遇到许可问题?该如何解决!?
评估许可证实际采购量? 
不清楚软件许可证使用数据? 
收到软件厂商律师函!?  
想要少购买点许可证,节省费用? 
收到软件厂商侵权通告!?  
有正版license,但许可证不够用,需要新购? 
联系方式 board-phone 155-2731-8020
close1
预留信息,一起解决您的问题
* 姓名:
* 手机:

* 公司名称:

姓名不为空

姓名不为空

姓名不为空
手机不正确

手机不正确

手机不正确
公司不为空

公司不为空

公司不为空