学习笔记19 10 月, 2026· 约 21 分钟
Unity 打包与 SDK
Unity 打包与 SDK 一、多平台打包 Unity多平台打包核心: 同一套工程资源与C 业务代码,针对不同目标平台做编译转换、资源处理,输出对应平台可运行程序包 。 底层:C++引擎内核做平台抽象;C 脚本根据平台选择Mono/IL2CPP后端;资源根据平台做纹理压缩、格式转换。 1. 核心基础概念 1. Scri
Unity 打包与 SDK
一、多平台打包
Unity多平台打包核心:同一套工程资源与C#业务代码,针对不同目标平台做编译转换、资源处理,输出对应平台可运行程序包。
底层:C++引擎内核做平台抽象;C#脚本根据平台选择Mono/IL2CPP后端;资源根据平台做纹理压缩、格式转换。
1. 核心基础概念
- Scripting Backend(脚本后端)
- Windows/Mac编辑器:默认Mono
- 发布Android / iOS:强制使用 IL2CPP(AOT)
- WebGL:IL2CPP
- PC桌面Windows:可选Mono或IL2CPP
iOS不允许JIT,只能IL2CPP。
- 平台相关资源处理 打包时Unity自动处理资源:
- 纹理:不同平台使用不同纹理压缩格式(安卓ETC2,iOS PVRTC,PC BC)
- 模型、音频自动转平台适合格式
- Plugins文件夹按平台过滤,只打包对应平台原生插件(SDK aar/framework)
- 条件编译
#if UNITY_ANDROID
//安卓代码
#elif UNITY_IOS
//iOS代码
#elif UNITY_STANDALONE_WIN
//Windows
#elif UNITY_WEBGL
//网页
#else
//编辑器/其他平台
#endif
只在对应平台编译生效,编辑器不会执行被条件编译屏蔽的代码。
2. 主流平台输出产物
| 目标平台 | 输出产物 | 脚本后端 | 备注 |
|---|---|---|---|
| Windows(PC) | .exe + Data文件夹 | Mono / IL2CPP | 可直接运行;也可打包安装包 |
| MacOS | .app应用包 | Mono / IL2CPP | 需要签名 |
| Android | APK / AAB | IL2CPP | AAB用于Google商店,APK本地安装 |
| iOS | Xcode工程文件夹 | IL2CPP | Unity不直接输出ipa;需要用Xcode编译签名出ipa |
| WebGL | html+js+wasm资源包 | IL2CPP | 浏览器运行,不支持多线程完整能力 |
⚠️iOS打包:Unity导出的是XCode工程,不是最终ipa;必须在Mac电脑打开Xcode,配置证书签名,编译生成ipa。Windows机器不能打包iOS。
3. 完整通用打包流程
- 切换目标平台
File → Build Settings,选中目标平台,点击
Switch Platform。
Switch Platform会重新导入、转换全部资源,耗时较长;会修改工程内部资源导入设置。 不同平台纹理压缩、资源设置不一样,切换平台会重新处理资源。
- 配置Player Settings Edit → Project Settings → Player
- 包名(Bundle Identifier):Android applicationId、iOS BundleID,必须和SDK后台注册一致
- 版本号Version、Build号
- 图标、启动页Splash Screen
- 权限、支持设备方向(横屏/竖屏)
- IL2CPP配置:架构选择
- Android:ARM64(现代手机,必选),可选择x86_64模拟器
- iOS:ARM64
- Windows:x86‑64
配置Scripting Backend 移动端全部选择IL2CPP;勾选目标CPU架构。
插件配置Plugins Plugins/Android、Plugins/iOS,Inspector面板勾选对应平台,过滤其他平台。 SDK的aar、framework、so库只有目标平台打包才打进包。
Build Settings设置
- Add Open Scenes:把需要的场景加入打包列表
- 输出路径,点击Build / Build And Run。
各平台特殊要点
Android
- 可选择导出Gradle工程,或者直接输出APK/AAB。
- 自定义AndroidManifest,配置权限、SDK Activity。
- EDM4U管理第三方SDK Gradle依赖,解决版本冲突。
- 架构:现在主流只保留ARM64,32位ARMv7基本废弃。
- AAB上传GooglePlay;APK用于国内渠道测试。
iOS
- 必须Mac系统打包导出Xcode工程。Windows无法导出iOS可用工程。
- 导出完成后打开Xcode:配置BundleID、开发证书、Provisioning Profile签名。
- PostProcessBuild脚本自动修改XCode工程配置:增加framework、链接库、设置Swift版本。
- Info.plist配置权限、白名单,SDK需要的配置项。
- 最终Archive打包输出ipa。
Windows PC
- IL2CPP打包会生成大量C++源码,打包速度慢;Mono打包速度快。
- 输出exe和配套_Data文件夹,不能单独拷贝exe运行,整个文件夹一起分发。
WebGL
- 只支持IL2CPP;不支持多线程、部分系统API。
- 输出html、wasm、js;需要部署http服务器,不能直接双击本地html打开。
4. 打包扩展:BuildPipeline / CI自动打包
Unity支持脚本化打包API,可以写Editor脚本实现一键打包,配合CI(GitHub Actions、Jenkins)自动化构建多平台包。
简单示例Editor脚本:
using UnityEditor;
public static class BuildTool
{
[MenuItem("Build/BuildAndroid")]
public static void BuildAndroid()
{
BuildPlayerOptions opts = new BuildPlayerOptions();
opts.scenes = EditorBuildSettings.scenes.Select(s=>s.path).ToArray();
opts.locationPathName = "Build/Android/test.apk";
opts.target = BuildTarget.Android;
opts.options = BuildOptions.None;
BuildPipeline.BuildPlayer(opts);
}
}
CI自动化打包适合多平台频繁构建,不用手动点编辑器。
5. 多平台打包高频坑
切换平台很慢 Switch Platform会重新导入全部资源;大工程切换平台等待时间久。团队开发建议不要频繁来回切平台。
IL2CPP代码裁剪(Stripping) IL2CPP会裁剪没有直接引用的C#代码;SDK回调、反射、热更新dll用到的类会被删掉,线上闪退。 解决:配置
link.xml保留类不被裁剪。HybridCLR必须配置link.xml。平台资源不兼容 纹理压缩格式平台不同,不要强行跨平台复用导入设置。
SDK多平台插件错误打包 Plugins没有勾选平台,安卓包里打入iOS framework导致打包报错。
iOS导出Xcode工程被覆盖 每次重新导出会覆盖Xcode工程,不要手动修改Xcode工程设置!所有修改写PostProcessBuild脚本,否则重新导出全部丢失。
BundleID错误 登录、支付SDK校验包名,BundleID不对SDK直接初始化失败。
WebGL本地直接打开html报错 WebGL必须部署HTTP服务,浏览器禁止本地file协议加载wasm。
6. 最佳实践
- 业务代码尽量平台无关,平台差异全部隔离到统一接口,用条件编译封装。
- iOS所有XCode工程修改全部写PostProcessBuild,不手动改工程。
- Android用EDM4U管理SDK依赖,自定义Manifest。
- 大项目尽量做CI自动化打包,减少人工操作失误。
- 区分测试包与正式包:开关日志、调试SDK/正式SDK。
如果你需要,我可以给一份PostProcessBuild的示例代码,或者CI打包脚本模板。
7. 补充与易错点
- Android 签名:Player Settings 里配 Keystore(密钥库、别名、密码),或用
BuildPipeline的PlayerSettings.Android.keyaliasPass在 CI 里注入。丢失 keystore 意味着无法覆盖更新已上架的包。 - AAB 与 APK 的区别:AAB 是上传给 Google Play 的分发格式,由商店按设备切分资源;国内渠道和本地测试仍用 APK。两者资源结构不同,测试要分别验证。
- 剥离等级(Managed Stripping Level):等级越高包体越小,但反射用的类型越容易被裁。上线前用真机跑一遍全流程,或保证
link.xml覆盖完整。 - Development Build 不是发布包:它带调试符号和 Profiler 连接能力,性能数据与正式包有差异,性能结论要以 Release 包为准。
- 包体优化的大头是纹理:压缩格式、分辨率、Mipmap、Read/Write 开关的收益远大于代码优化;先用打包分析工具看资源占比,再动手。
- 每次导出 iOS 工程都会覆盖:所有 Xcode 侧配置必须写进
PostProcessBuild,手改一定会在下次导出时丢失。
二、SDK 接入原理
SDK(登录、支付、广告、统计、推送)大多是原生平台SDK:Android用Java/Kotlin,iOS用OC/Swift。 Unity C#不能直接调用系统原生API,必须通过插件桥接层完成 C# ↔ 原生代码互相调用。
整体分层
- 上层:C#业务层:游戏业务逻辑,统一对外封装SDK接口
- 桥接层:Unity插件机制,C#与Java/OC跨语言通信
- 底层:原生SDK:Android AAR/JAR/.so、iOS Framework/.a,真正实现登录/支付等功能
⚠️编辑器下无法运行移动端SDK,只能真机打包调试。
1. 目录与插件机制
Unity识别特殊文件夹Plugins,做平台隔离编译
Assets/
└── Plugins/
├── Android/ # 仅Android打包生效
│ ├── xxx.aar # Android库,包含java、资源、Manifest、so库
│ ├── xxx.jar
│ └── AndroidManifest.xml
└── iOS/ # 仅iOS打包生效
├── xxx.framework
└── libxxx.a
选中插件文件,Inspector勾选对应平台,打包时Unity自动把这些原生库打进APK/IPA包中。
2. 双向通信原理
Android端(C# ↔ Java/Kotlin)
- C#调用Java
使用
AndroidJavaClass、AndroidJavaObject,底层基于JNI跨虚拟机调用;需要拿到Unity的currentActivity上下文,很多SDK初始化必须Activity对象。
#if UNITY_ANDROID
//拿到UnityPlayerActivity
AndroidJavaClass unityPlayerCls = new AndroidJavaClass("com.unity3d.player.UnityPlayer");
AndroidJavaObject activity = unityPlayerCls.GetStatic<AndroidJavaObject>("currentActivity");
//调用SDK静态/实例方法
activity.Call("showToast","测试");
#endif
- Java回调C#
UnityPlayer.UnitySendMessage("对象名","方法名","字符串参数")- 限制:目标GameObject名字必须固定;回调函数签名只能是
void Func(string msg);只能传字符串;异步延迟一帧;子线程调用容易丢失消息或崩溃。
- 限制:目标GameObject名字必须固定;回调函数签名只能是
- 高级:
AndroidJavaProxy接口代理,可以传递复杂参数。
Java层注意:SDK回调经常跑在子线程,必须切回Android UI线程
runOnUiThread,再执行UnitySendMessage,否则异常崩溃。
iOS端(C# ↔ Objective‑C)
- C#调用OC
C#使用
[DllImport("__Internal")]声明extern C函数,直接链接原生C符号;OC代码包装一层C导出函数供C#调用。
#if UNITY_IOS
[DllImport("__Internal")]
private static extern void SDK_Init(string appId);
#endif
- OC回调C#
同样使用C函数
UnitySendMessage("GameObject","Func","json")。>
⚠️iOS原生SDK回调经常在GCD后台队列,必须手动Dispatch切换到主线程再调用UnitySendMessage,否则直接崩溃。
重要:跨平台条件编译
#if UNITY_ANDROID
//安卓逻辑
#elif UNITY_IOS
//iOS逻辑
#else
//编辑器/PC占位,防止编辑器报错
#endif
3. SDK接入标准工作流
- 下载第三方SDK,拿到Android(aar/jar/so)、iOS(framework/a)原生库。
- 将原生库放入Plugins对应目录,配置插件导入设置。
- Manifest / Info.plist配置:Android权限、Activity;iOS权限、白名单、LSApplicationQueriesSchemes。
- C#封装统一SDK对外接口,隔离Android/iOS平台差异。
- 写PostProcessBuild打包后脚本(Editor脚本)
- Android:修改Gradle依赖,处理冲突;使用EDM4U自动解析依赖。
- iOS:自动修改XCode工程,添加Framework、设置编译参数,避免每次手动改Xcode。
- 游戏启动初始化SDK;做生命周期处理
OnPause/OnResume。 - 真机测试:初始化、登录、支付回调、App前后台切换、杀进程重启。
EDM4U:Google的Unity包,自动解析Android Gradle依赖,解决多个SDK之间依赖版本冲突。
4. SDK封装架构最佳实践
业务层不直接写
#if UNITY_ANDROID到处散落在业务代码。
SDKManager(业务统一调用层,无平台分支)
└── ISDKApi 接口定义(Init、Login、Pay、Share)
├── AndroidSDKImpl #if UNITY_ANDROID
├── IosSDKImpl #if UNITY_IOS
└── DummySDKImpl #编辑器PC空实现,编辑器运行不报错
业务只调用SDKManager.Instance.Login(),底层自动走不同平台实现。
回调全部用C#事件Action<string>,不要到处写UnitySendMessage硬编码。
5. 高频踩坑(非常重要)
- 线程问题(最多崩溃来源)>
Android/iOS SDK回调经常跑在子线程!
- 原生子线程不能直接操作原生UI;
- 原生子线程直接调用
UnitySendMessage会消息丢失、随机崩溃。 ✅解决方案:原生层把回调调度回平台主线程,再通知Unity。
- UnitySendMessage缺点 只能传字符串;GameObject名字不能改;不能传复杂对象。建议全部用JSON序列化传递数据。
- AndroidManifest冲突
多个SDK各自带Manifest,合并冲突;需要自定义Custom Main Manifest。
SDK的Activity必须继承
UnityPlayerActivity,否则会黑屏闪退。 - IL2CPP托管代码剥离(Stripping)
Release打包IL2CPP会裁剪未被直接引用的C#代码;SDK回调、反射用到的类被删掉,导致线上闪退。
解决:
link.xml保留需要的类不被裁剪。 - iOS打包坑
- Swift SDK需要设置Swift版本;需要嵌入Swift标准库。
- 缺少系统Framework链接,打包报错;用PostProcessBuild自动加。
- Bitcode已经废弃,新版本Xcode不再支持。
- 生命周期丢失
App切后台、回到前台,SDK需要通知
OnPause/OnResume;部分SDK不处理会丢失回调。 - 编辑器无法调试真机SDK PC/Editor只能跑Dummy空实现,登录支付必须真机打包。
6. 两种SDK接入模式
- 官方提供UnityPackage(推荐) 第三方已经封装好C#桥接层,直接导入unitypackage,只需填AppID。例如友盟、腾讯广点通。
- 只有原生SDK,自己写桥接 自己写Android Studio生成AAR、iOS写OC包装层;自己写C#桥接,工作量大。适合自研SDK。
7. 和热更新关系
SDK初始化、Activity、Manifest、iOS Info.plist、原生库属于AOT/原生包内容,不能热更新。
- SDK版本升级,必须重新发App商店包;
- 业务层调用SDK的C#逻辑可以放到HybridCLR热更DLL;但SDK本身无法热更。
简短总结
SDK接入本质:C#不直接碰原生系统API,靠插件桥接层做跨语言互调;Android用JNI,iOS用C‑DllImport;原生回调绝大多数跑子线程,务必切回平台主线程再通知Unity;Manifest、权限、XCode配置、代码剥离是最容易踩坑的点。
如果你需要,我可以给一份极简ISDK接口封装示例,或者PostProcessBuild示例。
8. 补充与易错点
- JNI 引用会泄漏:
AndroidJavaObject/AndroidJavaClass持有 JNI 全局引用,用完必须Dispose()(或using)。频繁创建不释放,会在 Java 堆外累积,表现为长时间运行后崩溃。 UnitySendMessage的开销与限制:字符串序列化 + 按名字反射找方法,性能差且只能传一个字符串参数;高频回调应改走AndroidJavaProxy(安卓)或函数指针回调(iOS)。- 原生回调的线程是最大坑:安卓的 SDK 回调常在子线程、iOS 常在 GCD 队列,必须切回主线程再
UnitySendMessage,否则随机崩溃。 - AAR 冲突要靠 EDM4U:多个 SDK 依赖同一库的不同版本时,Gradle 会报 duplicate class;EDM4U 做依赖解析与版本对齐。
- iOS 混编:OC 与 Swift 混用时,桥接文件要写成
.mm(Objective-C++),否则会与 Unity 的 C++ 符号冲突;Swift 还要设置SWIFT_VERSION并嵌入标准库。 - 权限要在两处配:Android 的
AndroidManifest.xml、iOS 的Info.plist,漏一个就是"功能静默失败",而不是崩溃。

