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 依賴。