__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 的“不支持的特性”文档,第一条就是:
不支持在热更新代码中定义 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 上就是不通的。
__Internal 必须在 AOT 里要真正理解这个坑,得回到 IL2CPP 的编译流程。Unity 在 iOS 上的工作流是:
这意味着:只有参与了第 2、3 步的代码,才能和 .mm 文件里的符号“面对面”。主工程(AOT 程序集)的代码走完了这条完整链路,所以主工程里的 [DllImport("__Internal")] 在 AOT 编译阶段就被识别成了“指向本二进制内部某个符号的调用”,IL2CPP 会为它生成完整的 marshal 代码,运行时直接函数指针调用,根本不走 dlopen。hybridclr.cn
热更程序集的 DLL 是运行时下载的 IL 字节码,它压根没参与过那两次编译,所以它里面的 DllImport 只能被当成一个“运行时再去查动态库”的请求——而 iOS 没有动态库可查,于是报错。
补充元数据机制(HybridCLR 给 AOT 补泛型元数据的那套)也救不了这个场景。补充元数据解决的是“AOT 里已有的类型在热更侧能用”,它不解决“热更侧调用一个 AOT 里根本不存在的 native 符号”——因为主包构建时那个符号对应的桥接函数就没生成,运行时无路可走。

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();
// ... 走登录流程
}
}
几个细节必须做对:
NativeApi,运行时是通过 AOT 已编译好的方法调用 native,不走任何动态查找。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
}
void CallNative(string method, string jsonArgs),热更侧传 JSON 字符串过去,原生侧自己解析,这样后续加新功能就不需要动 AOT 层。这是 iOS 真机上和 DllNotFoundException 一起出现频率最高的另一个坑,顺手一起讲了。
iOS 用 IL2CPP 编译时会有 Code Stripping,把没被主工程直接引用的类型和方法全部裁掉。热更代码里用到的 AOT 类型,如果主工程没显式引用,就被裁掉了,运行时报 TypeLoadException 或 MissingMethodException。
解决方案两层:
HybridCLR/Generate/LinkXml 菜单命令,能一键扫描热更代码里引用的 AOT 类型并生成 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 显式引用验证,不要只依赖热更侧反射去访问,因为裁剪优先级和反射查找优先级有时候会互相打架,真机上莫名其妙就是找不到类型。
桥接另一头——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
严格说,热更程序集里写 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 上是生死线,统一执行能省掉一半的跨平台排错时间。
如果你项目还在 HybridCLR v8.x,并且热更程序集里有 DllImport,升级 v9 后会直接抛 ExecutionEngineException: not support extern method: xxxx。官方给的迁移步骤就是本文第三节的做法:
[DllImport] 的 extern 函数声明;NativeApi);HybridCLR/Generate/All,重新打包主包。如果 native 接口在发布主包时还不确定,在 AOT 中预留——这是唯一办法,AOT 层的签名没法热更。
商业版的 DHE(差分混合执行)技术确实支持在 DHE 程序集中直接定义 extern 函数,但那是付费方案,开源版老老实实按“DllImport 全部放 AOT”来就行。
核心一句话记住就够:iOS 的 native 符号只对参与了 AOT 编译的代码可见,热更程序集永远不参与 AOT 编译,所以所有 DllImport 必须放 AOT,热更侧只通过 AOT 的静态类间接调用。 这条规则建立起来后,剩下的问题基本就是 link.xml 裁剪、回调线程、Editor Mock 这类工程化细节,按本文的清单排查就行。
免责声明:本文系网络转载或改编,未找到原创作者,版权归原作者所有。如涉及版权,请联系删