学习笔记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. 核心基础概念

  1. Scripting Backend(脚本后端)
  • Windows/Mac编辑器:默认Mono
  • 发布Android / iOS:强制使用 IL2CPP(AOT)
  • WebGL:IL2CPP
  • PC桌面Windows:可选Mono或IL2CPP

iOS不允许JIT,只能IL2CPP。

  1. 平台相关资源处理 打包时Unity自动处理资源:
  • 纹理:不同平台使用不同纹理压缩格式(安卓ETC2,iOS PVRTC,PC BC)
  • 模型、音频自动转平台适合格式
  • Plugins文件夹按平台过滤,只打包对应平台原生插件(SDK aar/framework)
  1. 条件编译
#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. 完整通用打包流程

  1. 切换目标平台 File → Build Settings,选中目标平台,点击Switch Platform。

Switch Platform会重新导入、转换全部资源,耗时较长;会修改工程内部资源导入设置。 不同平台纹理压缩、资源设置不一样,切换平台会重新处理资源。

  1. 配置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
  1. 配置Scripting Backend 移动端全部选择IL2CPP;勾选目标CPU架构。

  2. 插件配置Plugins Plugins/Android、Plugins/iOS,Inspector面板勾选对应平台,过滤其他平台。 SDK的aar、framework、so库只有目标平台打包才打进包。

  3. Build Settings设置

  • Add Open Scenes:把需要的场景加入打包列表
  • 输出路径,点击Build / Build And Run。

各平台特殊要点

Android
  1. 可选择导出Gradle工程,或者直接输出APK/AAB。
  2. 自定义AndroidManifest,配置权限、SDK Activity。
  3. EDM4U管理第三方SDK Gradle依赖,解决版本冲突。
  4. 架构:现在主流只保留ARM64,32位ARMv7基本废弃。
  5. AAB上传GooglePlay;APK用于国内渠道测试。
iOS
  1. 必须Mac系统打包导出Xcode工程。Windows无法导出iOS可用工程。
  2. 导出完成后打开Xcode:配置BundleID、开发证书、Provisioning Profile签名。
  3. PostProcessBuild脚本自动修改XCode工程配置:增加framework、链接库、设置Swift版本。
  4. Info.plist配置权限、白名单,SDK需要的配置项。
  5. 最终Archive打包输出ipa。
Windows PC
  1. IL2CPP打包会生成大量C++源码,打包速度慢;Mono打包速度快。
  2. 输出exe和配套_Data文件夹,不能单独拷贝exe运行,整个文件夹一起分发。
WebGL
  1. 只支持IL2CPP;不支持多线程、部分系统API。
  2. 输出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. 多平台打包高频坑

  1. 切换平台很慢 Switch Platform会重新导入全部资源;大工程切换平台等待时间久。团队开发建议不要频繁来回切平台。

  2. IL2CPP代码裁剪(Stripping) IL2CPP会裁剪没有直接引用的C#代码;SDK回调、反射、热更新dll用到的类会被删掉,线上闪退。 解决:配置link.xml保留类不被裁剪。HybridCLR必须配置link.xml。

  3. 平台资源不兼容 纹理压缩格式平台不同,不要强行跨平台复用导入设置。

  4. SDK多平台插件错误打包 Plugins没有勾选平台,安卓包里打入iOS framework导致打包报错。

  5. iOS导出Xcode工程被覆盖 每次重新导出会覆盖Xcode工程,不要手动修改Xcode工程设置!所有修改写PostProcessBuild脚本,否则重新导出全部丢失。

  6. BundleID错误 登录、支付SDK校验包名,BundleID不对SDK直接初始化失败。

  7. WebGL本地直接打开html报错 WebGL必须部署HTTP服务,浏览器禁止本地file协议加载wasm。

6. 最佳实践

  1. 业务代码尽量平台无关,平台差异全部隔离到统一接口,用条件编译封装。
  2. iOS所有XCode工程修改全部写PostProcessBuild,不手动改工程。
  3. Android用EDM4U管理SDK依赖,自定义Manifest。
  4. 大项目尽量做CI自动化打包,减少人工操作失误。
  5. 区分测试包与正式包:开关日志、调试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# ↔ 原生代码互相调用。

整体分层

  1. 上层:C#业务层:游戏业务逻辑,统一对外封装SDK接口
  2. 桥接层:Unity插件机制,C#与Java/OC跨语言通信
  3. 底层:原生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)

  1. 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
  1. Java回调C#
  • UnityPlayer.UnitySendMessage("对象名","方法名","字符串参数")
    • 限制:目标GameObject名字必须固定;回调函数签名只能是void Func(string msg);只能传字符串;异步延迟一帧;子线程调用容易丢失消息或崩溃。
  • 高级:AndroidJavaProxy接口代理,可以传递复杂参数。

Java层注意:SDK回调经常跑在子线程,必须切回Android UI线程runOnUiThread,再执行UnitySendMessage,否则异常崩溃。

iOS端(C# ↔ Objective‑C)

  1. 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
  1. OC回调C# 同样使用C函数UnitySendMessage("GameObject","Func","json")。>

⚠️iOS原生SDK回调经常在GCD后台队列,必须手动Dispatch切换到主线程再调用UnitySendMessage,否则直接崩溃。

重要:跨平台条件编译

#if UNITY_ANDROID
//安卓逻辑
#elif UNITY_IOS
//iOS逻辑
#else
//编辑器/PC占位,防止编辑器报错
#endif

3. SDK接入标准工作流

  1. 下载第三方SDK,拿到Android(aar/jar/so)、iOS(framework/a)原生库。
  2. 将原生库放入Plugins对应目录,配置插件导入设置。
  3. Manifest / Info.plist配置:Android权限、Activity;iOS权限、白名单、LSApplicationQueriesSchemes。
  4. C#封装统一SDK对外接口,隔离Android/iOS平台差异。
  5. 写PostProcessBuild打包后脚本(Editor脚本)
    • Android:修改Gradle依赖,处理冲突;使用EDM4U自动解析依赖。
    • iOS:自动修改XCode工程,添加Framework、设置编译参数,避免每次手动改Xcode。
  6. 游戏启动初始化SDK;做生命周期处理OnPause/OnResume。
  7. 真机测试:初始化、登录、支付回调、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. 高频踩坑(非常重要)

  1. 线程问题(最多崩溃来源)>

Android/iOS SDK回调经常跑在子线程!

  • 原生子线程不能直接操作原生UI;
  • 原生子线程直接调用UnitySendMessage会消息丢失、随机崩溃。 ✅解决方案:原生层把回调调度回平台主线程,再通知Unity。
  1. UnitySendMessage缺点 只能传字符串;GameObject名字不能改;不能传复杂对象。建议全部用JSON序列化传递数据。
  2. AndroidManifest冲突 多个SDK各自带Manifest,合并冲突;需要自定义Custom Main Manifest。 SDK的Activity必须继承UnityPlayerActivity,否则会黑屏闪退。
  3. IL2CPP托管代码剥离(Stripping) Release打包IL2CPP会裁剪未被直接引用的C#代码;SDK回调、反射用到的类被删掉,导致线上闪退。 解决:link.xml保留需要的类不被裁剪。
  4. iOS打包坑
  • Swift SDK需要设置Swift版本;需要嵌入Swift标准库。
  • 缺少系统Framework链接,打包报错;用PostProcessBuild自动加。
  • Bitcode已经废弃,新版本Xcode不再支持。
  1. 生命周期丢失 App切后台、回到前台,SDK需要通知OnPause/OnResume;部分SDK不处理会丢失回调。
  2. 编辑器无法调试真机SDK PC/Editor只能跑Dummy空实现,登录支付必须真机打包。

6. 两种SDK接入模式

  1. 官方提供UnityPackage(推荐) 第三方已经封装好C#桥接层,直接导入unitypackage,只需填AppID。例如友盟、腾讯广点通。
  2. 只有原生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,漏一个就是"功能静默失败",而不是崩溃。