# 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 官方文档