256 lines
5.2 KiB
Markdown
256 lines
5.2 KiB
Markdown
# 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 官方文档
|