文档；

2025-11-25 14:14:57 +08:00 · 2025-11-25 14:14:57 +08:00 · d8ff714ad8
commit d8ff714ad8
parent 1256b5db50
3 changed files with 558 additions and 1 deletions
--- a/README.md
+++ b/README.md
@ -1 +1,148 @@
-"Unity 集成iOS工程"
+# UnityFramework Pod
+
+Unity iOS Framework 打包为 CocoaPods，支持真机和模拟器。
+
+## 特性
+
+- ✅ 支持真机运行（完整 Unity 运行时）
+- ✅ 支持模拟器运行（空壳实现，用于开发调试）
+- ✅ XCFramework 格式，自动处理不同平台
+- ✅ 简单的升级流程
+
+## 架构支持
+
+| 平台 | 架构 | 说明 |
+|------|------|------|
+| 真机 | arm64 | 完整的 Unity 运行时 |
+| 模拟器 | arm64, x86_64 | 空壳实现，方便开发 |
+
+## 使用方法
+
+### 在 Podfile 中引入
+
+#### 使用 Git 仓库（推荐）
+
+```ruby
+pod 'UnityFramework', :git => 'https://gitea.sdws.shop/xim/flutter_unity_pod.git', :tag => '1.0.7'
+```
+
+#### 使用本地路径（开发调试）
+
+```ruby
+pod 'UnityFramework', :path => '/path/to/flutter_unity_pod'
+```
+
+### 安装
+
+```bash
+cd ios
+pod install
+```
+
+## 升级 Framework
+
+当有新的 Unity Framework 导出时，使用自动化脚本升级：
+
+```bash
+./upgrade_framework.sh /path/to/new/UnityFramework.framework
+```
+
+详细步骤请参考 [UPGRADE_GUIDE.md](./UPGRADE_GUIDE.md)
+
+## 项目结构
+
+```
+flutter_unity_pod/
+├── UnityLibrary/
+│   └── UnityFramework.xcframework/      # 主 XCFramework
+│       ├── ios-arm64/                    # 真机版本
+│       │   └── UnityFramework.framework/
+│       └── ios-arm64_x86_64-simulator/   # 模拟器版本
+│           └── UnityFramework.framework/
+├── simulator_stub/
+│   └── UnityFrameworkStub.m              # 模拟器空壳实现
+├── build_xcframework.sh                  # 初始构建脚本
+├── upgrade_framework.sh                  # 升级脚本
+├── UPGRADE_GUIDE.md                      # 升级指南
+└── UnityFramework.podspec                # Pod 配置文件
+```
+
+## 开发说明
+
+### 模拟器行为
+
+模拟器版本是空壳实现，所有 Unity 相关方法都会返回空或不执行。当尝试在模拟器运行 Unity 时，会输出日志：
+
+```
+UnityFramework: Simulator stub - Unity not available
+```
+
+在 Flutter 代码中也有检测：
+
+```dart
+// lib/common/utils/unitygame/unity_game_manager.dart:997-1004
+if (Platform.isIOS) {
+  final isSimulator =
+      Platform.environment.containsKey('SIMULATOR_DEVICE_NAME') ||
+          Platform.environment.containsKey('SIMULATOR_UDID');
+  if (isSimulator) {
+    showToast('Unity 游戏仅支持真机运行，请在真机上体验。');
+    return;
+  }
+}
+```
+
+### 构建流程
+
+1. 编译模拟器空壳（arm64 + x86_64）
+2. 合并真机 framework
+3. 创建 XCFramework
+4. 打包为 CocoaPod
+
+## 版本历史
+
+### 1.0.7 (2024-11-25)
+- 升级到 XCFramework
+- 添加模拟器支持
+- 简化配置，移除架构排除
+
+### 1.0.6
+- 初始版本
+- 仅支持真机
+
+## 故障排除
+
+### 模拟器构建失败
+
+确保 XCFramework 包含模拟器架构：
+
+```bash
+lipo -info UnityLibrary/UnityFramework.xcframework/ios-arm64_x86_64-simulator/UnityFramework.framework/UnityFramework
+```
+
+### 真机构建失败
+
+检查真机 framework 是否完整：
+
+```bash
+ls UnityLibrary/UnityFramework.xcframework/ios-arm64/UnityFramework.framework/
+```
+
+### Pod install 失败
+
+清理缓存重试：
+
+```bash
+pod cache clean UnityFramework --all
+rm -rf Pods Podfile.lock
+pod install
+```
+
+## License
+
+MIT
+
+## 联系方式
+
+- 仓库：https://gitea.sdws.shop/xim/flutter_unity_pod
+- 问题反馈：请创建 Issue
--- a/UPGRADE_GUIDE.md
+++ b/UPGRADE_GUIDE.md
@ -0,0 +1,255 @@
+# Unity Framework 升级指南
+
+本指南说明如何在导出新的真机 UnityFramework 后，将其升级到 Pod 库中。
+
+## 前置条件
+
+- 已从 Unity 导出新的 iOS Framework（真机版本）
+- 该 Framework 包含 arm64 架构
+
+## 快速升级（推荐）
+
+### 使用自动化脚本
+
+```bash
+cd /Users/apple/Desktop/work/flutter_unity_pod
+./upgrade_framework.sh /path/to/new/UnityFramework.framework
+```
+
+脚本会自动完成以下步骤：
+1. ✅ 验证新 Framework 的架构
+2. 📦 备份当前 XCFramework
+3. 🔨 编译模拟器空壳版本
+4. 🔄 合并真机和模拟器版本
+5. 📥 替换旧的 XCFramework
+
+## 手动升级步骤
+
+如果需要手动升级，请按以下步骤操作：
+
+### 1. 替换真机 Framework
+
+```bash
+# 进入 Pod 仓库
+cd /Users/apple/Desktop/work/flutter_unity_pod
+
+# 备份当前版本（可选）
+cp -r UnityLibrary/UnityFramework.xcframework backup/
+
+# 删除旧的 XCFramework
+rm -rf UnityLibrary/UnityFramework.xcframework
+```
+
+### 2. 运行构建脚本
+
+```bash
+# 先将新的 framework 放到临时位置
+cp -r /path/to/new/UnityFramework.framework /tmp/
+
+# 修改 build_xcframework.sh 中的路径
+# 将 DEVICE_FRAMEWORK 变量改为新的 framework 路径
+
+# 运行构建脚本
+./build_xcframework.sh
+```
+
+### 3. 更新版本号（如果需要）
+
+编辑 `UnityFramework.podspec`：
+
+```ruby
+s.version = '1.0.8'  # 更新版本号
+```
+
+### 4. 提交到 Git
+
+```bash
+# 添加所有更改
+git add -A
+
+# 提交
+git commit -m "更新 Unity framework 到版本 x.x.x
+
+- 更新游戏资源到最新版本
+- 修复 xxx bug
+- 添加 xxx 功能"
+
+# 打标签（使用与 podspec 相同的版本号）
+git tag 1.0.8
+
+# 推送到远程
+git push origin main
+git push origin 1.0.8
+```
+
+## 在主项目中使用新版本
+
+### 使用本地路径（开发测试）
+
+在主项目的 `ios/Podfile` 中：
+
+```ruby
+pod 'UnityFramework', :path => '/Users/apple/Desktop/work/flutter_unity_pod'
+```
+
+然后运行：
+```bash
+cd ios
+rm -rf Pods Podfile.lock
+pod install
+```
+
+### 使用 Git 仓库（正式发布）
+
+在主项目的 `ios/Podfile` 中：
+
+```ruby
+pod 'UnityFramework', :git => 'https://gitea.sdws.shop/xim/flutter_unity_pod.git', :tag => '1.0.8'
+```
+
+然后运行：
+```bash
+cd ios
+rm -rf Pods Podfile.lock
+pod install
+```
+
+## 验证升级
+
+### 1. 验证 XCFramework 结构
+
+```bash
+# 查看 XCFramework 包含的平台
+xcodebuild -checkFirstLaunchStatus \
+  /Users/apple/Desktop/work/flutter_unity_pod/UnityLibrary/UnityFramework.xcframework
+```
+
+应该看到：
+- ✅ ios-arm64（真机）
+- ✅ ios-arm64_x86_64-simulator（模拟器）
+
+### 2. 测试模拟器构建
+
+```bash
+cd /path/to/main/project
+flutter build ios --simulator --debug
+```
+
+### 3. 测试真机构建
+
+```bash
+cd /path/to/main/project
+flutter build ios --release --no-codesign
+```
+
+## 常见问题
+
+### Q: 升级后模拟器无法运行？
+
+A: 检查模拟器空壳是否正确编译：
+```bash
+cd /Users/apple/Desktop/work/flutter_unity_pod
+file UnityLibrary/UnityFramework.xcframework/ios-arm64_x86_64-simulator/UnityFramework.framework/UnityFramework
+```
+
+应该显示包含 `arm64` 和 `x86_64` 架构。
+
+### Q: 升级后真机无法运行？
+
+A: 检查真机 framework 是否包含所有必需的文件：
+```bash
+ls -la UnityLibrary/UnityFramework.xcframework/ios-arm64/UnityFramework.framework/
+```
+
+应该包含：
+- Headers/
+- Data/
+- UnityFramework（二进制文件）
+- Info.plist
+- Modules/
+
+### Q: Git 推送失败（权限不足）？
+
+A: 联系仓库管理员配置写权限，或者先在本地测试通过后再推送。
+
+## 版本管理建议
+
+### 版本号规则
+
+遵循语义化版本：`major.minor.patch`
+
+- **major**: Unity 主版本升级（如 2021 -> 2022）
+- **minor**: 游戏功能更新、重大修改
+- **patch**: Bug 修复、小优化
+
+### 示例
+- `1.0.7`: 初始 XCFramework 版本
+- `1.0.8`: 修复 bug
+- `1.1.0`: 添加新游戏
+- `2.0.0`: Unity 版本升级
+
+## 自动化 CI/CD（可选）
+
+如果希望自动化升级流程，可以创建 CI 脚本：
+
+```yaml
+# .github/workflows/upgrade-framework.yml
+name: Upgrade Unity Framework
+
+on:
+  workflow_dispatch:
+    inputs:
+      framework_url:
+        description: 'Unity Framework 下载 URL'
+        required: true
+
+jobs:
+  upgrade:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Download Framework
+        run: |
+          curl -L ${{ github.event.inputs.framework_url }} -o framework.zip
+          unzip framework.zip
+
+      - name: Upgrade Framework
+        run: ./upgrade_framework.sh ./UnityFramework.framework
+
+      - name: Commit and Tag
+        run: |
+          git config user.name "CI Bot"
+          git config user.email "ci@example.com"
+          git add -A
+          git commit -m "Auto upgrade framework"
+          git tag 1.0.${{ github.run_number }}
+          git push origin main --tags
+```
+
+## 回滚步骤
+
+如果升级后出现问题，可以快速回滚：
+
+```bash
+# 查看备份
+ls backup/
+
+# 恢复备份
+cp -r backup/backup_YYYYMMDD_HHMMSS/UnityFramework.xcframework \
+      UnityLibrary/
+
+# 回退 git 提交
+git reset --hard HEAD~1
+
+# 删除标签
+git tag -d 1.0.x
+git push origin :refs/tags/1.0.x
+```
+
+## 支持
+
+如有问题，请联系开发团队或查看：
+- 项目 README
+- Unity 导出文档
+- CocoaPods 官方文档
--- a/upgrade_framework.sh
+++ b/upgrade_framework.sh
@ -0,0 +1,155 @@
+#!/bin/bash
+set -e
+
+echo "=== UnityFramework 升级脚本 ==="
+echo ""
+
+# 检查参数
+if [ "$#" -ne 1 ]; then
+    echo "用法: $0 <新的真机Framework路径>"
+    echo "示例: $0 /path/to/new/UnityFramework.framework"
+    exit 1
+fi
+
+NEW_FRAMEWORK="$1"
+REPO_DIR="/Users/apple/Desktop/work/flutter_unity_pod"
+STUB_DIR="$REPO_DIR/simulator_stub"
+BUILD_DIR="$REPO_DIR/build"
+
+# 验证新的 framework 是否存在
+if [ ! -d "$NEW_FRAMEWORK" ]; then
+    echo "❌ 错误: Framework 不存在: $NEW_FRAMEWORK"
+    exit 1
+fi
+
+# 验证是否是真机架构
+ARCH=$(lipo -info "$NEW_FRAMEWORK/UnityFramework" 2>/dev/null | grep "arm64" || echo "")
+if [ -z "$ARCH" ]; then
+    echo "❌ 错误: Framework 不包含 arm64 架构，请确保是真机版本"
+    exit 1
+fi
+
+echo "✅ 验证通过: 找到真机 Framework"
+echo ""
+
+# 清理之前的构建
+echo "1. 清理旧构建..."
+rm -rf "$BUILD_DIR"
+mkdir -p "$BUILD_DIR"
+
+# 备份当前 XCFramework（可选）
+if [ -d "$REPO_DIR/UnityLibrary/UnityFramework.xcframework" ]; then
+    BACKUP_DIR="$REPO_DIR/backup_$(date +%Y%m%d_%H%M%S)"
+    echo "2. 备份当前 XCFramework 到: $BACKUP_DIR"
+    mkdir -p "$BACKUP_DIR"
+    cp -r "$REPO_DIR/UnityLibrary/UnityFramework.xcframework" "$BACKUP_DIR/"
+fi
+
+echo "3. 编译模拟器空壳 framework..."
+cd "$STUB_DIR"
+
+# 编译 arm64 模拟器版本
+xcrun clang -arch arm64 \
+    -isysroot $(xcrun --sdk iphonesimulator --show-sdk-path) \
+    -target arm64-apple-ios13.0-simulator \
+    -dynamiclib \
+    -o "$BUILD_DIR/UnityFramework_sim_arm64" \
+    -framework Foundation -framework UIKit \
+    -install_name @rpath/UnityFramework.framework/UnityFramework \
+    UnityFrameworkStub.m
+
+# 编译 x86_64 模拟器版本
+xcrun clang -arch x86_64 \
+    -isysroot $(xcrun --sdk iphonesimulator --show-sdk-path) \
+    -target x86_64-apple-ios13.0-simulator \
+    -dynamiclib \
+    -o "$BUILD_DIR/UnityFramework_sim_x86_64" \
+    -framework Foundation -framework UIKit \
+    -install_name @rpath/UnityFramework.framework/UnityFramework \
+    UnityFrameworkStub.m
+
+echo "4. 合并模拟器架构..."
+lipo -create \
+    "$BUILD_DIR/UnityFramework_sim_arm64" \
+    "$BUILD_DIR/UnityFramework_sim_x86_64" \
+    -output "$BUILD_DIR/UnityFramework_sim"
+
+echo "5. 创建模拟器 framework 结构..."
+SIM_FRAMEWORK="$BUILD_DIR/UnityFramework-sim.framework"
+mkdir -p "$SIM_FRAMEWORK/Headers"
+mkdir -p "$SIM_FRAMEWORK/Modules"
+
+# 复制二进制
+cp "$BUILD_DIR/UnityFramework_sim" "$SIM_FRAMEWORK/UnityFramework"
+
+# 从新的真机 framework 复制头文件
+cp -r "$NEW_FRAMEWORK/Headers/" "$SIM_FRAMEWORK/Headers/"
+
+# 创建 module.modulemap
+cat > "$SIM_FRAMEWORK/Modules/module.modulemap" << 'EOF'
+framework module UnityFramework {
+  umbrella header "UnityFramework.h"
+  export *
+  module * { export * }
+}
+EOF
+
+# 创建 Info.plist
+cat > "$SIM_FRAMEWORK/Info.plist" << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleExecutable</key>
+    <string>UnityFramework</string>
+    <key>CFBundleIdentifier</key>
+    <string>com.unity3d.framework</string>
+    <key>CFBundleInfoDictionaryVersion</key>
+    <string>6.0</string>
+    <key>CFBundleName</key>
+    <string>UnityFramework</string>
+    <key>CFBundlePackageType</key>
+    <string>FMWK</string>
+    <key>CFBundleShortVersionString</key>
+    <string>1.0</string>
+    <key>CFBundleVersion</key>
+    <string>1</string>
+    <key>MinimumOSVersion</key>
+    <string>13.0</string>
+</dict>
+</plist>
+EOF
+
+echo "6. 创建 XCFramework..."
+# 创建临时目录
+DEVICE_BUILD="$BUILD_DIR/device"
+SIM_BUILD="$BUILD_DIR/simulator"
+mkdir -p "$DEVICE_BUILD" "$SIM_BUILD"
+
+# 复制新的真机 framework
+cp -r "$NEW_FRAMEWORK" "$DEVICE_BUILD/UnityFramework.framework"
+
+# 移动模拟器 framework
+mv "$SIM_FRAMEWORK" "$SIM_BUILD/UnityFramework.framework"
+
+# 创建 XCFramework
+xcodebuild -create-xcframework \
+    -framework "$DEVICE_BUILD/UnityFramework.framework" \
+    -framework "$SIM_BUILD/UnityFramework.framework" \
+    -output "$BUILD_DIR/UnityFramework.xcframework"
+
+echo "7. 替换旧的 XCFramework..."
+rm -rf "$REPO_DIR/UnityLibrary/UnityFramework.xcframework"
+cp -r "$BUILD_DIR/UnityFramework.xcframework" "$REPO_DIR/UnityLibrary/"
+
+echo ""
+echo "✅ 升级完成！新的 XCFramework 已创建在:"
+echo "   $REPO_DIR/UnityLibrary/UnityFramework.xcframework"
+echo ""
+echo "📝 后续步骤:"
+echo "   1. 检查 XCFramework 是否正常"
+echo "   2. 更新 podspec 版本号（如果需要）"
+echo "   3. 提交到 git: git add -A && git commit -m 'Update Unity framework'"
+echo "   4. 打标签: git tag 1.0.x"
+echo "   5. 推送: git push origin main && git push origin 1.0.x"
+echo ""