跳转到内容

42. 版本管理和备份

约 50 分钟 内容:进阶 动手章

版本控制记录项目在每次提交时的状态,用于比较修改、恢复文件和协作。备份另存一份数据,用于设备损坏或仓库不可用时恢复。两者可以配合,但本地 Git 仓库不会自动备份到其他设备。

在 Edit → Project Settings → Editor 中检查 Asset Serialization → Mode 为 Force Text。它让支持 Unity 序列化的场景、Prefab、Material 等资源以文本形式保存;图片、音频和模型等二进制源文件不会因此变成 YAML。

在 Project Settings 的 Version Control 设置中确认使用 Visible Meta Files;旧版本界面可能将该项放在 Editor 分类。

Unity 用 .meta 记录资源的 GUID 与导入设置。场景对资源的引用依赖 GUID,不只是文件名。

  • 资源与同名 .meta 一起提交、移动、重命名和删除。
  • 在 Unity Project 面板内移动资源,可由编辑器同时维护 .meta。
  • .gitignore 不应整体忽略 *.meta。
  • 如果拉取后出现 Missing,检查对应 .meta 是否丢失或 GUID 改变,不要随意重新生成后直接提交。

Force Text 使差异可读,但不保证所有冲突都能自动合并。

项目根目录与 Assets、Packages、ProjectSettings 同级放置 .gitignore。可从 GitHub 的 Unity 模板开始,按实际项目调整。

.gitignore 基础示例
# Unity 缓存和临时目录
/[Ll]ibrary/
/[Tt]emp/
/[Oo]bj/
/[Ll]ogs/
/[Uu]ser[Ss]ettings/
/[Mm]emoryCaptures/
/[Rr]ecordings/
# 本地构建输出
/[Bb]uild/
/[Bb]uilds/
*.apk
*.aab
# IDE 生成文件
.vs/
.idea/
*.csproj
*.sln
*.suo
*.user
*.userprefs
# 本地日志与系统文件
*.log
.DS_Store
Thumbs.db
# Blender 自动备份
*.blend1
*.blend1.meta

核心提交范围是 Assets/、Packages/ 和 ProjectSettings/,加上项目说明、许可证、.gitignore 与 .gitattributes。记录准确的 Unity 版本及依赖版本,才能判断其他机器是否具备恢复条件。

不要只按扩展名忽略所有 .asset、.bytes 或包目录;它们可能包含不可重建的源数据。UdonSharp 生成目录是否可忽略,需要结合当前版本和工程的干净恢复测试决定,本示例不预先排除它们。

.gitignore 只影响未跟踪文件。已提交的缓存不会因新增规则自动从历史中移除。

先保存工程并检查待提交文件:

Terminal window
cd C:\Projects\YourWorld
git init
git add .gitignore
git status --short
git add Assets Packages ProjectSettings
git diff --cached --stat
git status --short
git commit -m "chore: record world project baseline"

检查输出中没有 Library、临时构建、账号信息或不应分发的资源。.meta 和必要依赖文件应在提交范围内。

若 Library 已被跟踪,在确认路径正确后可用 git rm --cached -r Library 从当前索引移除,再提交;--cached 保留工作目录文件。这不会删除旧提交中的内容。清理已公开或共享的历史属于另一项操作,会改变提交 ID,需要与合作者协调。

每次提交包含一个可说明的改动,并用 git diff 检查内容。提交只保存已加入索引的文件;未保存到磁盘的编辑器状态和未跟踪文件不在其中。

仓库体积异常增长时,可在普通仓库的根目录用 PowerShell 记录 .git 占用,再查实际跟踪的缓存文件:

Terminal window
Get-ChildItem .git -Recurse -Force -File | Measure-Object -Property Length -Sum
git ls-files Library Temp Builds

Sum 是文件字节数,可能包括本地 LFS 对象;它不是远端配额或项目质量的判断线。第二条若列出缓存,先核对是否误跟踪;即使本次为空,旧历史仍可能占空间。Git worktree 的 .git 可能是指向仓库的文件,不能照此统计目录。

提交消息可写 feat: add local mirror switch、fix: restore late-join state、art: replace wall material、chore: update SDK 或 refactor: split door state logic。前缀是可选约定,具体改了什么才是查历史时需要的信息。

较大的二进制模型、纹理、音频和视频可以由 Git LFS 管理。Git 历史保存指针,实际内容存在 LFS 对象存储中。合作者需要安装 LFS 并取得这些对象,只有指针文件不能恢复完整项目。

选择确实需要 LFS 的类型,在首次添加这些文件前配置:

Terminal window
git lfs install
git lfs track "*.fbx" "*.blend" "*.psd" "*.exr" "*.wav" "*.mp4"
git add .gitattributes
git lfs track
git lfs ls-files

生成的 .gitattributes 条目例如:

*.fbx filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -text

已经进入普通 Git 历史的文件,不会因 track 自动迁移旧版本。git lfs migrate 会涉及历史改写;先备份并确认共享仓库的影响,再按官方文档操作。

远端 Git 与 LFS 分别有文件、存储和流量限制。额度与费用按托管服务和套餐查证,不在工程模板里假定固定免费容量。若源文件单独保存到其他存储,记录它们的版本、获取方式和恢复步骤。

两个人修改同一 Scene 时,文本合并可能产生引用冲突。Unity 的 Smart Merge 工具 UnityYAMLMerge 理解场景与 Prefab 的序列化结构,可辅助合并,但仍需要检查结果。

在项目根目录执行 git config --local --edit,把下面的配置加入仓库的 .git/config;已有同名段落时合并字段,不再复制一组。这个作用域只影响当前本地仓库,文件不会随 git push 传给合作者。

如果要让本机当前用户的其他仓库也使用它,改用 git config --global --edit 编辑用户配置,通常是 ~/.gitconfig(Windows 通常为 C:/Users/<用户名>/.gitconfig)。全局默认可被仓库配置覆盖;有不同 Unity 版本的项目时,分别用仓库配置指定路径。不要把这一段写进 .gitignore 或 .gitattributes。

以下沿用官方 Git mergetool 调用方式,并用 Git 配置文件的转义保留文件参数的引号:

[merge]
tool = unityyamlmerge
[mergetool "unityyamlmerge"]
trustExitCode = false
cmd = "'<UNITY_INSTALL>/Editor/Data/Tools/UnityYAMLMerge.exe' merge -p \"$BASE\" \"$REMOTE\" \"$LOCAL\" \"$MERGED\""

将 <UNITY_INSTALL> 替换为对应 Unity 编辑器的安装根目录,例如 C:/Program Files/Unity/Hub/Editor/<版本>。不要把 Editor/Data 重复拼入路径。

保存后在项目目录检查生效值与来源:

Terminal window
git config --show-origin --get merge.tool
git config --show-origin --get mergetool.unityyamlmerge.cmd

第一条应为 unityyamlmerge,第二条应含实际存在的工具路径;输出同时指出配置文件。协作者需在各自机器配置自己的 Unity 路径。

发生冲突后:

Terminal window
git status
git mergetool

UnityYAMLMerge 的 Tools/mergespecfile.txt 配置未解决冲突时使用的后备工具。若提示找不到后备工具,检查该文件指向的程序是否已安装,不要把工具退出当成冲突解决。

确认每个冲突都已处理,再打开 Unity 检查对象、引用、Prefab 覆盖和场景运行结果,最后提交。

这份配置由 git mergetool 调用,不会自动接管每次普通 git merge。.gitattributes 的 merge driver 是另一套配置,不应仅加一条 merge=unityyamlmerge 就假定生效。

协作中可以把独立区域拆成 Prefab,并协调谁修改主场景;这能减少同时编辑范围,但不能消除所有冲突。

保留 Packages/manifest.json、适用的锁文件、Packages/vpm-manifest.json 与 ProjectSettings/ProjectVersion.txt。Unity Package Manager 与 VPM 各自记录依赖,不能只保留其中一个清单就假定完整。

对包内容区分:

  • 可从已记录来源、版本重新取得的包,可以在验证恢复流程后按项目规则处理。
  • 手动修改、嵌入或来源不可再访问的包,需要保存其实际内容和授权。
  • 本地路径依赖要说明相对位置,不能只依赖作者电脑上的绝对路径。

在新目录 clone 后,通过 VCC / VPM 的恢复功能检查依赖,再用匹配的 Unity 打开。不要把“Open Project 一定自动还原所有包”作为未验证的恢复保证。

远端仓库的可见性和合作者权限应与素材授权一致。Private 限制访问,但不会自动赋予合作者使用付费资源的许可。

创建适当权限的远端后,按其真实地址连接:

Terminal window
git remote add origin <你的远端仓库地址>
git branch -M main
git push -u origin main

推送成功后,确认远端存在预期提交;使用 LFS 时也要确认对象上传成功。后续可以用以下步骤保存改动:

Terminal window
git status
git diff
git add <本次改动的文件>
git diff --cached
git commit -m "fix: restore door state for late joiners"
git push

备份可采用关闭 Unity 后的项目快照、独立存储或外接硬盘副本。避免把正在导入和写入的工程直接当作已验证的一致快照。Reimport All 只是重新导入已有源文件,不是备份,也不能恢复已删除的源文件。

发布时记录源代码提交、World ID、平台、SDK 版本和构建日期。Git tag 可以标记对应源码:

Terminal window
git tag -a publish-1.0 -m "Source used for the first public release"
git push origin publish-1.0

需要检查旧版时,先保存当前工作,再从标记建立恢复分支:

Terminal window
git switch -c recovery/publish-1.0 publish-1.0

重新构建不保证与旧包字节相同;Unity、SDK、依赖和烘焙条件都可能影响产物。上传恢复版前仍需测试,并确认目标 World ID。

一次完整恢复检查:

  1. 在独立目录 clone,并取回 LFS 对象。
  2. 还原依赖,使用记录的 Unity 版本打开。
  3. 检查 Console、场景引用、材质、脚本与烘焙资源。
  4. 执行关键功能与构建测试。
  5. 把缺失的资源、权限或步骤补入恢复说明。

在测试工程中提交一次已知可用状态,再改动一个材质和一个脚本并提交。用 git log 与 git diff 找到差异,在独立分支恢复前一版本并验证场景。多人合并练习应使用同一个场景文件的两条分支,分别修改独立对象,检查合并后的结果。