xim/flutter_unity_pod

Fork 0

zj d8ff714ad8 文档；

2025-11-25 14:14:57 +08:00

5.2 KiB

Raw Blame History

Unity Framework 升级指南

本指南说明如何在导出新的真机 UnityFramework 后，将其升级到 Pod 库中。

前置条件

已从 Unity 导出新的 iOS Framework（真机版本）
该 Framework 包含 arm64 架构

快速升级（推荐）

使用自动化脚本

cd /Users/apple/Desktop/work/flutter_unity_pod
./upgrade_framework.sh /path/to/new/UnityFramework.framework

脚本会自动完成以下步骤：

✅ 验证新 Framework 的架构
📦 备份当前 XCFramework
🔨 编译模拟器空壳版本
🔄 合并真机和模拟器版本
📥 替换旧的 XCFramework

手动升级步骤

如果需要手动升级，请按以下步骤操作：

1. 替换真机 Framework

# 进入 Pod 仓库
cd /Users/apple/Desktop/work/flutter_unity_pod

# 备份当前版本（可选）
cp -r UnityLibrary/UnityFramework.xcframework backup/

# 删除旧的 XCFramework
rm -rf UnityLibrary/UnityFramework.xcframework

2. 运行构建脚本

# 先将新的 framework 放到临时位置
cp -r /path/to/new/UnityFramework.framework /tmp/

# 修改 build_xcframework.sh 中的路径
# 将 DEVICE_FRAMEWORK 变量改为新的 framework 路径

# 运行构建脚本
./build_xcframework.sh

3. 更新版本号（如果需要）

编辑 UnityFramework.podspec：

s.version = '1.0.8'  # 更新版本号

4. 提交到 Git

# 添加所有更改
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 中：

pod 'UnityFramework', :path => '/Users/apple/Desktop/work/flutter_unity_pod'

然后运行：

cd ios
rm -rf Pods Podfile.lock
pod install

使用 Git 仓库（正式发布）

在主项目的 ios/Podfile 中：

pod 'UnityFramework', :git => 'https://gitea.sdws.shop/xim/flutter_unity_pod.git', :tag => '1.0.8'

然后运行：

cd ios
rm -rf Pods Podfile.lock
pod install

验证升级

1. 验证 XCFramework 结构

# 查看 XCFramework 包含的平台
xcodebuild -checkFirstLaunchStatus \
  /Users/apple/Desktop/work/flutter_unity_pod/UnityLibrary/UnityFramework.xcframework

应该看到：

✅ ios-arm64（真机）
✅ ios-arm64_x86_64-simulator（模拟器）

2. 测试模拟器构建

cd /path/to/main/project
flutter build ios --simulator --debug

3. 测试真机构建

cd /path/to/main/project
flutter build ios --release --no-codesign

常见问题

Q: 升级后模拟器无法运行？

A: 检查模拟器空壳是否正确编译：

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 是否包含所有必需的文件：

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 脚本：

# .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

回滚步骤

如果升级后出现问题，可以快速回滚：

# 查看备份
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 官方文档

5.2 KiB Raw Blame History Unescape Escape