XGRIDS文档

iOS 设备编译打包开发指南

背景说明

LCC Unity SDK 以预编译 DLL 形式发布。由于 iOS 平台要求原生插件以静态库方式链接（__Internal），而非动态加载（dlopen），在构建 iOS 应用前需要完成本文档描述的额外配置步骤。iOS 与其他平台在原生插件加载机制上存在根本差异，其他平台（Windows、macOS、Android、Linux）无需任何额外操作。

本 SDK 在编译为 DLL 时使用了 "libwebp" 作为 P/Invoke 目标。SDK 内置的 Editor/RewriteWebpDllImport.cs 脚本会在 iOS 构建时自动将其重写为 "__Internal"，确保 IL2CPP 生成正确的直接符号调用。

注意：

在需要编译 iOS 设备应用时，请先将SDK 包中 Editor/RewriteWebpDllImport.txt 重命名为 Editor/RewriteWebpDllImport.cs，脚本才会生效。或者直接将SDK包中该脚本修改后辍后拷贝到工程的 Assets/Editor/ 目录下。

前置条件

RewriteWebpDllImport.cs 脚本在构建时会用到 IL 重写库 Mono.Cecil，因此需要先将其作为依赖添加到工程中。有以下两种方式，任选其一。

方法一：通过 Package Manager 添加（推荐）

打开 Unity 菜单栏 Window → Package Manager ，点击左上角 + 号，选择 Add package by name... ，名称填入 com.unity.nuget.mono-cecil，版本填入 1.11.5，点击 Add ,等待 Package Manager 完成安装 ，如下图所示。

在 Package Manager 中通过名称添加 Mono.Cecil 依赖

在 Package Manager 中通过名称添加 com.unity.nuget.mono-cecil

方法二：手动编辑 manifest.json

直接编辑工程下的 Packages/manifest.json，在 dependencies 中添加一行：

{
  "dependencies": {
    "com.unity.nuget.mono-cecil": "1.11.5"
  }
}

保存后切回 Unity，编辑器会自动解析并安装该依赖。

构建流程

完成前置配置后，按标准 iOS 构建流程操作即可，RewriteWebpDllImport 会在构建过程中自动介入。

  1. 将 Editor/RewriteWebpDllImport.txt 重命名为 Editor/RewriteWebpDllImport.cs（若尚未重命名）。
  2. 在 Unity 菜单栏选择 File → Build Settings，在平台列表中选择 iOS，点击 Switch Platform。
  3. 点击 Build（或 Build And Run），选择输出目录，生成 Xcode 工程。
  4. 构建过程中，脚本会自动把 SDK 中所有以 "libwebp" 为目标的 DllImport 重写为 "__Internal"。构建成功后，Console 会输出类似日志：
[RewriteWebpDllImport] Rewrote 77 P/Invoke entries from "libwebp" to "__Internal".
  1. 用 Xcode 打开生成的工程，在 target 的 Build Phases → Link Binary With Libraries 中确认 libwebp.a、libwebpdemux.a、libsharpyuv.a 已被链接。
  2. 连接 iOS 设备，在 Xcode 中签名并运行。

说明：

若 Console 中未出现 [RewriteWebpDllImport] 日志，通常意味着脚本未生效——请确认文件后缀已从 .txt 改为 .cs，且 Mono.Cecil 依赖已正确安装。

故障排除

报错信息原因解决方法
Unable to load DLL 'libwebp'脚本未生效，DllImport 仍指向动态库名确认 RewriteWebpDllImport.txt 已重命名为 .cs，重新构建并检查 Console 日志
Cannot find LCCSDK.dll in staging area构建时未找到 SDK 主 DLL，重写目标缺失确认 SDK 已正确导入工程，DLL 未被 Exclude Platform 排除掉 iOS
Mono.Cecil 相关编译错误（找不到 Mono.Cecil 命名空间）未安装或版本不匹配按「前置条件」添加 com.unity.nuget.mono-cecil@1.11.5，等待编译器重新解析

注意事项

  • 建议使用 Unity 2022.3 LTS 或更高版本（含 Unity 6），过低版本对 Mono.Cecil 与 IL2CPP 的兼容性无法保证。
  • 若需要在 iOS 模拟器上运行，请确认所链接的静态库包含 arm64-simulator 架构切片，否则模拟器无法链接。
  • 上述配置仅影响 iOS 平台。Windows、macOS、Android、Linux 的构建流程不受任何影响，无需重命名脚本或添加 Mono.Cecil 依赖。