1. 从本地项目到云端仓库为什么Unity项目上传Github是个技术活如果你是一个Unity开发者手头有一个正在开发中的游戏或者工具项目想把代码托管到Github上无论是为了版本控制、团队协作还是单纯做个备份你可能会觉得这很简单不就是把整个项目文件夹拖到Github仓库里吗我刚开始也是这么想的结果第一次上传就踩了个大坑——上传了整整两个小时Github提示仓库大小超限或者上传了一堆根本不需要的临时文件把仓库弄得一团糟。Unity项目尤其是带有大量美术资源、插件和缓存文件的项目其文件结构远比一个纯代码项目复杂。直接上传整个Assets和Library文件夹无异于把建筑工地的所有建材、脚手架和建筑垃圾都打包寄给别人不仅体积巨大而且别人根本无法直接使用。所以Unity项目上传Github核心不是“上传”这个动作而是“整理”和“配置”。你需要告诉Git以及Github哪些是项目的“源代码”如脚本、预制体、场景文件哪些是运行时生成的“中间产物”如Library文件夹哪些是可以通过包管理器重新获取的“依赖”如通过Package Manager安装的包。这个过程本质上是在为你的项目建立一个清晰、可复现的构建蓝图。一个配置得当的Unity项目仓库应该能让任何克隆它的人在打开Unity编辑器后通过简单的几步操作比如重新导入资源、解析包依赖就得到一个和你本地几乎一模一样的可编译、可运行的项目状态而不是一个动辄几个G的庞然大物。接下来我会以一个典型的Unity项目为例带你走通从零配置到成功上传Github的完整流程。我们会重点关注.gitignore文件的魔力、Unity编辑器设置的关键项、Git客户端的正确使用以及如何验证你的仓库是否“干净”。这些步骤是我在多个项目协作和迁移中总结出来的能帮你避开90%的常见陷阱。2. 上传前的核心准备理解Unity项目的文件结构在动手之前我们必须先搞清楚Unity项目里哪些东西该上传哪些不该上传。一个新建的Unity项目其根目录下通常会有这些文件夹Assets: 这是你的核心工作目录。你编写的C#脚本、创建的材质球、预制体Prefab、场景Scene、音频、模型等所有游戏资源都放在这里。这个文件夹是必须上传的它是你项目的“血肉”。ProjectSettings: 存放项目的全局设置如图形质量设置、输入管理器配置、标签和图层、编辑器构建设置等。这个文件夹也必须上传它定义了项目的“骨架”和“规则”。Packages: 这里有一个manifest.json文件它记录了项目通过Unity Package Manager或其它方式安装的所有第三方包如Post Processing、TextMeshPro、Cinemachine等及其版本。只上传manifest.json文件而不是整个Packages文件夹。因为克隆仓库后Unity会根据这个文件自动从官方或指定源重新下载这些包这保证了依赖的一致性。Library: 这是Unity编辑器为了加速资源导入和项目加载而生成的本地缓存文件夹。它包含了Assets文件夹中所有资源的导入结果、元数据.meta文件的缓存、编译后的脚本等。这个文件夹绝对不要上传到Git。它体积巨大轻松上G且完全可以从Assets和ProjectSettings重新生成。上传它只会浪费空间和带宽。Temp,Obj,Logs等: 这些是编译、构建过程中生成的临时文件夹或日志文件。全部不要上传。Builds: 如果你在本地构建过游戏的可执行文件如.exe, .app这个文件夹也会很大。不要上传。构建产物应该通过CI/CD持续集成/持续部署流程生成或者单独存放。理解了这些我们的目标就明确了上传Assets、ProjectSettings以及Packages/manifest.json同时忽略掉所有由Unity自动生成或本地特有的文件和文件夹。实现这个目标的神器就是.gitignore文件。3. 创建与配置.gitignore为你的项目设置过滤规则.gitignore文件是一个纯文本文件放在你Git仓库的根目录。它里面每一行都是一个匹配模式告诉Git哪些文件或文件夹应该被忽略不纳入版本控制。对于Unity项目我们不需要从头编写这个文件因为社区已经有非常成熟和全面的模板。3.1 获取官方的Unity.gitignore模板最可靠的方法是直接从Github官方的gitignore仓库获取。你可以访问https://github.com/github/gitignore/blob/main/Unity.gitignore将页面中的全部内容复制下来。或者如果你已经安装了Git并且习惯使用命令行可以在项目根目录执行以下命令来下载并重命名# 从官方仓库拉取Unity的gitignore文件 curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Unity.gitignore这个官方的.gitignore模板已经包含了针对Library/、Temp/、Obj/、*.csprojVisual Studio项目文件可由Unity重新生成、Builds/等几乎所有需要忽略的条目。它是我们工作的坚实基础。3.2 根据项目情况微调.gitignore官方的模板是通用的但你的项目可能有特殊需求需要额外添加或删除一些规则。用文本编辑器如VS Code, Notepad打开你创建好的.gitignore文件在文件末尾进行修改。需要额外添加的常见情况忽略特定的大文件或文件夹如果你的Assets里有一些非常大的原始设计文件如.psd, .blend或者测试用的视频而它们并非运行时必需你可以选择忽略它们。# 忽略Assets目录下特定的巨型文件或文件夹 Assets/RawDesignFiles/*.psd Assets/TestVideos/注意这样做意味着其他协作者将不会拥有这些文件。你必须确保项目离开这些文件也能正常编译运行例如你已经导出了对应的.png或.fbx文件。忽略编辑器个性化设置UserSettings/文件夹保存了编辑器布局、快捷键等个人偏好通常不需要共享。# 忽略用户个人设置 UserSettings/官方的模板可能已经包含了这一项检查一下。忽略特定插件的缓存或可下载内容有些第三方资源商店的插件可能会在Assets内生成Documentation或Samples文件夹如果它们体积很大且非必需可以考虑忽略。# 示例忽略某个插件的示例文件 Assets/Plugins/SomeAssetStorePlugin/Samples/需要谨慎处理或删除规则的情况Assets/AssetStoreTools官方模板可能会忽略这个文件夹。但如果你或你的团队需要通过Unity Asset Store的打包工具来管理内部资产可能需要保留它。如果不确定先保留忽略规则。*.private文件模板可能会忽略所有以.private结尾的文件。这是一种约定俗成的做法用于存放包含密码、API密钥等敏感信息的配置文件。你需要确保这类敏感信息确实没有提交。更常见的做法是提交一个模板文件如config.private.template而将真实的config.private文件忽略。配置好.gitignore后一个关键动作是立即清除本地Git缓存。因为如果你之前已经用git add .添加过所有文件那些本应被忽略的文件可能已经被Git跟踪了。.gitignore只对未跟踪的文件生效。要清理缓存需要运行# 停止跟踪所有文件但保留工作区的文件本身 git rm -r --cached . # 重新添加所有文件此时.gitignore规则生效 git add .执行git status命令你应该看到只有Assets、ProjectSettings、Packages/manifest.json和.gitignore等少数文件被列为待提交而Library等文件夹消失了。这就对了。4. 关键的Unity编辑器设置确保跨平台一致性文件过滤好了接下来要确保项目本身在不同机器上打开时行为一致。这主要依赖于ProjectSettings里的配置但有几个地方需要特别检查。4.1 版本控制模式 (Version Control Mode)打开Unity编辑器进入Edit - Project Settings - Editor。 在Version Control部分将Mode设置为“Visible Meta Files”。 在Asset Serialization部分将Mode设置为“Force Text”。为什么是“Visible Meta Files”Unity会为Assets目录下的每个资源包括文件夹生成一个同名的.meta文件。这个文件记录了资源的GUID全局唯一标识符、导入设置如纹理的压缩格式等关键信息。设置为“Visible”意味着这些.meta文件会以普通文件的形式出现在你的资源管理器里并且必须被Git跟踪。如果丢失或错乱.meta文件会导致资源引用断裂比如一个预制体引用了一个材质球但材质球的GUID变了引用就失效了。为什么是“Force Text”默认情况下场景.scene、预制体.prefab等文件是以二进制格式存储的。二进制文件在Git中无法进行差异比较diff合并冲突时更是灾难。设置为“Force Text”后这些文件会以YAML这样的文本格式存储。虽然人类直接阅读稍有困难但Git可以清晰地看到哪一行被修改了极大地方便了代码审查和合并冲突解决。更改这些设置后Unity可能会提示你需要重新导入所有资源。同意即可。这个操作会更新所有的.meta文件。4.2 处理通过Package Manager安装的包确保你的Packages/manifest.json文件是正确的。这个文件应该只包含你主动安装的包而不是本地缓存的包。一个干净的manifest.json看起来像这样{ dependencies: { com.unity.cinemachine: 2.9.7, com.unity.textmeshpro: 3.0.6, com.unity.ugui: 1.0.0, com.unity.modules.ai: 1.0.0, // ... 其他模块和包 } }不要手动修改manifest.json除非你知道自己在做什么。通常通过Unity编辑器的Package Manager窗口进行安装、移除或版本更新是最安全的方式。4.3 一个常被忽略的坑场景中的临时对象或测试代码在提交前最好打开你的主要场景检查一下。有没有在场景中直接放置的、仅用于临时测试的游戏对象比如一个叫“TestCube”的Cube有没有在脚本里写了仅用于本地调试的Debug.Log语句或者写死的测试路径虽然这些不影响仓库的“纯净度”但提交它们会让协作者感到困惑。养成良好的习惯在提交前清理一下场景和代码中的“调试痕迹”。5. 使用Git命令行完成上传清晰可控的每一步虽然有很多图形化Git工具如Github Desktop, SourceTree但我强烈推荐至少掌握基本的Git命令行操作。它能让你更清晰地理解每个步骤背后发生了什么在遇到问题时也更容易排查。5.1 初始化本地仓库与首次提交假设你的Unity项目文件夹叫MyUnityGame并且已经按照上述步骤配置好了.gitignore和编辑器设置。打开终端或Git Bash导航到你的项目根目录。cd /path/to/your/MyUnityGame初始化Git仓库。git init这会在当前目录创建一个隐藏的.git文件夹它是Git的“数据库”。检查状态。这是你最常用的命令之一。git status此时你应该看到红色的文件列表显示所有未被跟踪的文件。理想情况下你应该只看到Assets、ProjectSettings、Packages/manifest.json、.gitignore以及一些必要的项目文件如MyUnityGame.sln解决方案文件如果你使用Visual Studio。绝对不应该看到Library或Temp。添加所有应跟踪的文件到暂存区。git add .这个点.代表当前目录所有文件但.gitignore的规则会生效。再次运行git status你会看到刚才红色的文件变成了绿色表示它们已被添加到暂存区准备提交。进行第一次提交。git commit -m Initial commit: Unity project with core assets and settings-m后面是提交信息。请务必写一个有意义的提交信息例如“添加玩家移动和跳跃功能”、“修复了敌人AI在墙角卡住的bug”。模糊的“update”或“fix”信息在日后回顾历史时会让人头疼。5.2 关联远程仓库并推送现在本地已经有了一个完整的版本历史。我们需要在Github上创建一个“空仓库”来接收它。在Github上创建新仓库。登录Github点击右上角“” - “New repository”。给仓库起个名字如MyUnityGame。不要勾选“Initialize this repository with a README”。因为我们本地已经有内容了如果远程仓库非空推送时会冲突。创建完成后你会看到一个快速设置页面其中包含远程仓库的URL类似https://github.com/yourname/MyUnityGame.git。将本地仓库与远程仓库关联。git remote add origin https://github.com/yourname/MyUnityGame.gitorigin是给这个远程仓库起的一个别名习惯上用origin。推送本地提交到远程仓库。git push -u origin main-u参数是--set-upstream的简写它会把本地的main分支和远程的main分支关联起来。这样以后在这个分支上直接运行git push或git pull就可以了无需再指定远程和分支名。第一次推送可能会弹出窗口让你输入Github的用户名和密码或Personal Access Token。如果使用HTTPS链接推荐使用Personal Access Token代替密码更安全。推送完成后刷新你的Github仓库页面就能看到所有文件都已经成功上传了。检查一下仓库的大小一个中等规模的Unity项目在正确忽略Library后通常只有几十MB甚至几MB而不是几个GB。6. 验证与协作如何确认你的仓库是“可复现”的上传成功不代表万事大吉。最关键的一步是验证这个仓库能否被其他人或者未来的你在另一台电脑上正确地克隆并打开6.1 进行“克隆测试”找一个干净的目录或者用另一台电脑执行克隆操作git clone https://github.com/yourname/MyUnityGame.git cd MyUnityGame打开Unity Hub使用“Add”按钮添加这个克隆下来的项目文件夹。Unity Hub会识别它为一个Unity项目。点击打开项目。观察并验证以下过程首次打开时间因为Library文件夹不存在Unity需要重新导入所有Assets下的资源并重建Library。这个过程可能会比较慢取决于项目资源多少这是正常的。如果打开飞快反而要检查是不是不小心把Library也传上去了。控制台报错打开后查看Unity控制台。允许有一些警告比如首次导入某些资源时的提示但不应该有大量的红色错误。常见的错误可能包括Missing meta files如果.gitignore配置错误导致.meta文件缺失你会看到大量“Missing .meta”错误。这需要回到源项目确保所有.meta文件都已提交。Script compilation errors如果C#脚本有语法错误或者依赖的命名空间/程序集找不到。检查Packages/manifest.json是否完整以及脚本本身是否有问题。Missing references in prefabs or scenes如果资源GUID错乱预制体或场景中引用的资源会丢失显示为“Missing”。这通常也是.meta文件问题或资源被移动/重命名后未正确提交导致的。运行测试尝试进入Play Mode看看游戏是否能正常运行。如果是一些基础功能如角色移动、UI点击可以工作说明仓库的核心部分是可用的。6.2 为协作者准备的README在项目根目录添加一个README.md文件这是一个好习惯。它应该包含项目简介这是什么游戏/工具开发环境建议的Unity版本如“2022.3 LTS”。这点非常重要不同Unity版本之间的项目可能存在兼容性问题。如何开始克隆仓库。用Unity Hub打开项目文件夹。等待Unity完成资源导入首次打开较慢。打开Assets/Scenes/MainScene.unity场景举例。点击播放按钮进行测试。关键依赖说明如果有必须通过Asset Store手动下载的插件因为某些付费插件无法通过manifest.json自动获取需要在这里写明名称和获取方式。把这个README.md文件也提交到Git仓库里。7. 进阶管理与常见问题排查当项目进入正常开发迭代后你还需要注意以下事项。7.1 处理大文件Git LFS的必要性即使忽略了Library如果你的Assets里包含大量高精度模型.fbx, .blend、原始音频.wav、高清视频.mp4等二进制大文件直接让Git管理它们效率会很低。因为Git会存储文件的每一个版本即使只修改了一点点也会产生一个新的完整副本导致仓库体积快速增长。这时就需要Git Large File Storage (LFS)。Git LFS会用“指针文件”替换掉仓库中的大文件而将实际的大文件内容存储在一个单独的服务器上如Github LFS。对于Unity项目通常建议对以下类型的文件使用LFS.psd,.tiff(大型图像源文件).fbx,.blend,.mb(3D模型文件).wav,.aiff(未压缩音频).mp4,.mov(视频文件)设置Git LFS的步骤安装Git LFS客户端从官网下载。在项目根目录运行git lfs install初始化。指定要跟踪的文件类型。创建一个名为.gitattributes的文件或编辑已有的添加规则例如# 跟踪所有fbx和blend文件 *.fbx filterlfs difflfs mergelfs -text *.blend filterlfs difflfs mergelfs -text # 跟踪所有超过10MB的wav文件 *.wav filterlfs difflfs mergelfs -text像往常一样git add .gitattributes和git add你的资源文件然后提交推送。注意Github对LFS有流量和存储限制免费账户每月有1GB的带宽和1GB的存储。对于超大型项目可能需要购买额度。7.2 合并冲突的解决尤其是场景和预制体当多人修改了同一个场景.unity或预制体.prefab文件并尝试合并时会发生冲突。因为即使它们是文本格式YAML其结构也非常复杂自动合并几乎总会出错。最佳实践是建立团队规则场景分工如果可能将一个大场景拆分为多个小的子场景Additive Loading或者为不同功能的开发者分配不同的场景文件。预制体编辑锁使用一些团队协作工具如Unity的Collaborate服务或第三方工具Plastic SCM提供的“文件锁定”功能防止多人同时编辑同一个预制体。手动合并当冲突不可避免时需要手动解决。不要直接接受“ours”或“theirs”。步骤备份冲突文件。在Unity编辑器中分别打开“我们的”版本和“他们的”版本可以通过临时切换分支实现。仔细对比两个版本中游戏对象层级Hierarchy和组件属性的差异。在文本编辑器中打开冲突的.unity或.prefab文件找到标记的冲突区块根据你在编辑器中观察到的差异手动编辑YAML文本保留正确的部分删除冲突标记。这是一个繁琐且容易出错的过程所以预防清晰的模块划分和沟通远比治疗重要。7.3 忽略规则不生效检查Git缓存如果你发现Library文件夹里的文件仍然出现在git status中即使.gitignore规则正确很可能是因为它们已经被Git跟踪了。如前所述使用git rm -r --cached Library命令将其从Git跟踪中移除但保留在本地磁盘然后重新提交。7.4 仓库体积依然过大使用BFG或git filter-branch清理历史如果历史提交中不小心引入了大文件比如一个巨大的.zip备份包即使后续的提交中删除了它这个文件仍然存在于Git的历史记录中会持续占用仓库空间。要彻底清理需要使用git filter-branch或更易用的工具如BFG Repo-Cleaner。这是一个高风险操作因为它会重写提交历史。在执行前务必确保所有协作者都已将他们的工作推送或备份因为重写历史后他们的本地历史将与远程不兼容需要强制拉取git pull --force或重新克隆。我个人更倾向于在项目早期就建立好规范的.gitignore和提交习惯避免将垃圾文件纳入版本控制这比事后清理要简单和安全得多。 
长河君 · 2026/8/12 18:46:29 · 阅读 1.2k Unity项目上传GitHub全攻略：从.gitignore配置到可复现仓库搭建
1. 从本地项目到云端仓库为什么Unity项目上传Github是个技术活如果你是一个Unity开发者手头有一个正在开发中的游戏或者工具项目想把代码托管到Github上无论是为了版本控制、团队协作还是单纯做个备份你可能会觉得这很简单不就是把整个项目文件夹拖到Github仓库里吗我刚开始也是这么想的结果第一次上传就踩了个大坑——上传了整整两个小时Github提示仓库大小超限或者上传了一堆根本不需要的临时文件把仓库弄得一团糟。Unity项目尤其是带有大量美术资源、插件和缓存文件的项目其文件结构远比一个纯代码项目复杂。直接上传整个Assets和Library文件夹无异于把建筑工地的所有建材、脚手架和建筑垃圾都打包寄给别人不仅体积巨大而且别人根本无法直接使用。所以Unity项目上传Github核心不是“上传”这个动作而是“整理”和“配置”。你需要告诉Git以及Github哪些是项目的“源代码”如脚本、预制体、场景文件哪些是运行时生成的“中间产物”如Library文件夹哪些是可以通过包管理器重新获取的“依赖”如通过Package Manager安装的包。这个过程本质上是在为你的项目建立一个清晰、可复现的构建蓝图。一个配置得当的Unity项目仓库应该能让任何克隆它的人在打开Unity编辑器后通过简单的几步操作比如重新导入资源、解析包依赖就得到一个和你本地几乎一模一样的可编译、可运行的项目状态而不是一个动辄几个G的庞然大物。接下来我会以一个典型的Unity项目为例带你走通从零配置到成功上传Github的完整流程。我们会重点关注.gitignore文件的魔力、Unity编辑器设置的关键项、Git客户端的正确使用以及如何验证你的仓库是否“干净”。这些步骤是我在多个项目协作和迁移中总结出来的能帮你避开90%的常见陷阱。2. 上传前的核心准备理解Unity项目的文件结构在动手之前我们必须先搞清楚Unity项目里哪些东西该上传哪些不该上传。一个新建的Unity项目其根目录下通常会有这些文件夹Assets: 这是你的核心工作目录。你编写的C#脚本、创建的材质球、预制体Prefab、场景Scene、音频、模型等所有游戏资源都放在这里。这个文件夹是必须上传的它是你项目的“血肉”。ProjectSettings: 存放项目的全局设置如图形质量设置、输入管理器配置、标签和图层、编辑器构建设置等。这个文件夹也必须上传它定义了项目的“骨架”和“规则”。Packages: 这里有一个manifest.json文件它记录了项目通过Unity Package Manager或其它方式安装的所有第三方包如Post Processing、TextMeshPro、Cinemachine等及其版本。只上传manifest.json文件而不是整个Packages文件夹。因为克隆仓库后Unity会根据这个文件自动从官方或指定源重新下载这些包这保证了依赖的一致性。Library: 这是Unity编辑器为了加速资源导入和项目加载而生成的本地缓存文件夹。它包含了Assets文件夹中所有资源的导入结果、元数据.meta文件的缓存、编译后的脚本等。这个文件夹绝对不要上传到Git。它体积巨大轻松上G且完全可以从Assets和ProjectSettings重新生成。上传它只会浪费空间和带宽。Temp,Obj,Logs等: 这些是编译、构建过程中生成的临时文件夹或日志文件。全部不要上传。Builds: 如果你在本地构建过游戏的可执行文件如.exe, .app这个文件夹也会很大。不要上传。构建产物应该通过CI/CD持续集成/持续部署流程生成或者单独存放。理解了这些我们的目标就明确了上传Assets、ProjectSettings以及Packages/manifest.json同时忽略掉所有由Unity自动生成或本地特有的文件和文件夹。实现这个目标的神器就是.gitignore文件。3. 创建与配置.gitignore为你的项目设置过滤规则.gitignore文件是一个纯文本文件放在你Git仓库的根目录。它里面每一行都是一个匹配模式告诉Git哪些文件或文件夹应该被忽略不纳入版本控制。对于Unity项目我们不需要从头编写这个文件因为社区已经有非常成熟和全面的模板。3.1 获取官方的Unity.gitignore模板最可靠的方法是直接从Github官方的gitignore仓库获取。你可以访问https://github.com/github/gitignore/blob/main/Unity.gitignore将页面中的全部内容复制下来。或者如果你已经安装了Git并且习惯使用命令行可以在项目根目录执行以下命令来下载并重命名# 从官方仓库拉取Unity的gitignore文件 curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Unity.gitignore这个官方的.gitignore模板已经包含了针对Library/、Temp/、Obj/、*.csprojVisual Studio项目文件可由Unity重新生成、Builds/等几乎所有需要忽略的条目。它是我们工作的坚实基础。3.2 根据项目情况微调.gitignore官方的模板是通用的但你的项目可能有特殊需求需要额外添加或删除一些规则。用文本编辑器如VS Code, Notepad打开你创建好的.gitignore文件在文件末尾进行修改。需要额外添加的常见情况忽略特定的大文件或文件夹如果你的Assets里有一些非常大的原始设计文件如.psd, .blend或者测试用的视频而它们并非运行时必需你可以选择忽略它们。# 忽略Assets目录下特定的巨型文件或文件夹 Assets/RawDesignFiles/*.psd Assets/TestVideos/注意这样做意味着其他协作者将不会拥有这些文件。你必须确保项目离开这些文件也能正常编译运行例如你已经导出了对应的.png或.fbx文件。忽略编辑器个性化设置UserSettings/文件夹保存了编辑器布局、快捷键等个人偏好通常不需要共享。# 忽略用户个人设置 UserSettings/官方的模板可能已经包含了这一项检查一下。忽略特定插件的缓存或可下载内容有些第三方资源商店的插件可能会在Assets内生成Documentation或Samples文件夹如果它们体积很大且非必需可以考虑忽略。# 示例忽略某个插件的示例文件 Assets/Plugins/SomeAssetStorePlugin/Samples/需要谨慎处理或删除规则的情况Assets/AssetStoreTools官方模板可能会忽略这个文件夹。但如果你或你的团队需要通过Unity Asset Store的打包工具来管理内部资产可能需要保留它。如果不确定先保留忽略规则。*.private文件模板可能会忽略所有以.private结尾的文件。这是一种约定俗成的做法用于存放包含密码、API密钥等敏感信息的配置文件。你需要确保这类敏感信息确实没有提交。更常见的做法是提交一个模板文件如config.private.template而将真实的config.private文件忽略。配置好.gitignore后一个关键动作是立即清除本地Git缓存。因为如果你之前已经用git add .添加过所有文件那些本应被忽略的文件可能已经被Git跟踪了。.gitignore只对未跟踪的文件生效。要清理缓存需要运行# 停止跟踪所有文件但保留工作区的文件本身 git rm -r --cached . # 重新添加所有文件此时.gitignore规则生效 git add .执行git status命令你应该看到只有Assets、ProjectSettings、Packages/manifest.json和.gitignore等少数文件被列为待提交而Library等文件夹消失了。这就对了。4. 关键的Unity编辑器设置确保跨平台一致性文件过滤好了接下来要确保项目本身在不同机器上打开时行为一致。这主要依赖于ProjectSettings里的配置但有几个地方需要特别检查。4.1 版本控制模式 (Version Control Mode)打开Unity编辑器进入Edit - Project Settings - Editor。 在Version Control部分将Mode设置为“Visible Meta Files”。 在Asset Serialization部分将Mode设置为“Force Text”。为什么是“Visible Meta Files”Unity会为Assets目录下的每个资源包括文件夹生成一个同名的.meta文件。这个文件记录了资源的GUID全局唯一标识符、导入设置如纹理的压缩格式等关键信息。设置为“Visible”意味着这些.meta文件会以普通文件的形式出现在你的资源管理器里并且必须被Git跟踪。如果丢失或错乱.meta文件会导致资源引用断裂比如一个预制体引用了一个材质球但材质球的GUID变了引用就失效了。为什么是“Force Text”默认情况下场景.scene、预制体.prefab等文件是以二进制格式存储的。二进制文件在Git中无法进行差异比较diff合并冲突时更是灾难。设置为“Force Text”后这些文件会以YAML这样的文本格式存储。虽然人类直接阅读稍有困难但Git可以清晰地看到哪一行被修改了极大地方便了代码审查和合并冲突解决。更改这些设置后Unity可能会提示你需要重新导入所有资源。同意即可。这个操作会更新所有的.meta文件。4.2 处理通过Package Manager安装的包确保你的Packages/manifest.json文件是正确的。这个文件应该只包含你主动安装的包而不是本地缓存的包。一个干净的manifest.json看起来像这样{ dependencies: { com.unity.cinemachine: 2.9.7, com.unity.textmeshpro: 3.0.6, com.unity.ugui: 1.0.0, com.unity.modules.ai: 1.0.0, // ... 其他模块和包 } }不要手动修改manifest.json除非你知道自己在做什么。通常通过Unity编辑器的Package Manager窗口进行安装、移除或版本更新是最安全的方式。4.3 一个常被忽略的坑场景中的临时对象或测试代码在提交前最好打开你的主要场景检查一下。有没有在场景中直接放置的、仅用于临时测试的游戏对象比如一个叫“TestCube”的Cube有没有在脚本里写了仅用于本地调试的Debug.Log语句或者写死的测试路径虽然这些不影响仓库的“纯净度”但提交它们会让协作者感到困惑。养成良好的习惯在提交前清理一下场景和代码中的“调试痕迹”。5. 使用Git命令行完成上传清晰可控的每一步虽然有很多图形化Git工具如Github Desktop, SourceTree但我强烈推荐至少掌握基本的Git命令行操作。它能让你更清晰地理解每个步骤背后发生了什么在遇到问题时也更容易排查。5.1 初始化本地仓库与首次提交假设你的Unity项目文件夹叫MyUnityGame并且已经按照上述步骤配置好了.gitignore和编辑器设置。打开终端或Git Bash导航到你的项目根目录。cd /path/to/your/MyUnityGame初始化Git仓库。git init这会在当前目录创建一个隐藏的.git文件夹它是Git的“数据库”。检查状态。这是你最常用的命令之一。git status此时你应该看到红色的文件列表显示所有未被跟踪的文件。理想情况下你应该只看到Assets、ProjectSettings、Packages/manifest.json、.gitignore以及一些必要的项目文件如MyUnityGame.sln解决方案文件如果你使用Visual Studio。绝对不应该看到Library或Temp。添加所有应跟踪的文件到暂存区。git add .这个点.代表当前目录所有文件但.gitignore的规则会生效。再次运行git status你会看到刚才红色的文件变成了绿色表示它们已被添加到暂存区准备提交。进行第一次提交。git commit -m Initial commit: Unity project with core assets and settings-m后面是提交信息。请务必写一个有意义的提交信息例如“添加玩家移动和跳跃功能”、“修复了敌人AI在墙角卡住的bug”。模糊的“update”或“fix”信息在日后回顾历史时会让人头疼。5.2 关联远程仓库并推送现在本地已经有了一个完整的版本历史。我们需要在Github上创建一个“空仓库”来接收它。在Github上创建新仓库。登录Github点击右上角“” - “New repository”。给仓库起个名字如MyUnityGame。不要勾选“Initialize this repository with a README”。因为我们本地已经有内容了如果远程仓库非空推送时会冲突。创建完成后你会看到一个快速设置页面其中包含远程仓库的URL类似https://github.com/yourname/MyUnityGame.git。将本地仓库与远程仓库关联。git remote add origin https://github.com/yourname/MyUnityGame.gitorigin是给这个远程仓库起的一个别名习惯上用origin。推送本地提交到远程仓库。git push -u origin main-u参数是--set-upstream的简写它会把本地的main分支和远程的main分支关联起来。这样以后在这个分支上直接运行git push或git pull就可以了无需再指定远程和分支名。第一次推送可能会弹出窗口让你输入Github的用户名和密码或Personal Access Token。如果使用HTTPS链接推荐使用Personal Access Token代替密码更安全。推送完成后刷新你的Github仓库页面就能看到所有文件都已经成功上传了。检查一下仓库的大小一个中等规模的Unity项目在正确忽略Library后通常只有几十MB甚至几MB而不是几个GB。6. 验证与协作如何确认你的仓库是“可复现”的上传成功不代表万事大吉。最关键的一步是验证这个仓库能否被其他人或者未来的你在另一台电脑上正确地克隆并打开6.1 进行“克隆测试”找一个干净的目录或者用另一台电脑执行克隆操作git clone https://github.com/yourname/MyUnityGame.git cd MyUnityGame打开Unity Hub使用“Add”按钮添加这个克隆下来的项目文件夹。Unity Hub会识别它为一个Unity项目。点击打开项目。观察并验证以下过程首次打开时间因为Library文件夹不存在Unity需要重新导入所有Assets下的资源并重建Library。这个过程可能会比较慢取决于项目资源多少这是正常的。如果打开飞快反而要检查是不是不小心把Library也传上去了。控制台报错打开后查看Unity控制台。允许有一些警告比如首次导入某些资源时的提示但不应该有大量的红色错误。常见的错误可能包括Missing meta files如果.gitignore配置错误导致.meta文件缺失你会看到大量“Missing .meta”错误。这需要回到源项目确保所有.meta文件都已提交。Script compilation errors如果C#脚本有语法错误或者依赖的命名空间/程序集找不到。检查Packages/manifest.json是否完整以及脚本本身是否有问题。Missing references in prefabs or scenes如果资源GUID错乱预制体或场景中引用的资源会丢失显示为“Missing”。这通常也是.meta文件问题或资源被移动/重命名后未正确提交导致的。运行测试尝试进入Play Mode看看游戏是否能正常运行。如果是一些基础功能如角色移动、UI点击可以工作说明仓库的核心部分是可用的。6.2 为协作者准备的README在项目根目录添加一个README.md文件这是一个好习惯。它应该包含项目简介这是什么游戏/工具开发环境建议的Unity版本如“2022.3 LTS”。这点非常重要不同Unity版本之间的项目可能存在兼容性问题。如何开始克隆仓库。用Unity Hub打开项目文件夹。等待Unity完成资源导入首次打开较慢。打开Assets/Scenes/MainScene.unity场景举例。点击播放按钮进行测试。关键依赖说明如果有必须通过Asset Store手动下载的插件因为某些付费插件无法通过manifest.json自动获取需要在这里写明名称和获取方式。把这个README.md文件也提交到Git仓库里。7. 进阶管理与常见问题排查当项目进入正常开发迭代后你还需要注意以下事项。7.1 处理大文件Git LFS的必要性即使忽略了Library如果你的Assets里包含大量高精度模型.fbx, .blend、原始音频.wav、高清视频.mp4等二进制大文件直接让Git管理它们效率会很低。因为Git会存储文件的每一个版本即使只修改了一点点也会产生一个新的完整副本导致仓库体积快速增长。这时就需要Git Large File Storage (LFS)。Git LFS会用“指针文件”替换掉仓库中的大文件而将实际的大文件内容存储在一个单独的服务器上如Github LFS。对于Unity项目通常建议对以下类型的文件使用LFS.psd,.tiff(大型图像源文件).fbx,.blend,.mb(3D模型文件).wav,.aiff(未压缩音频).mp4,.mov(视频文件)设置Git LFS的步骤安装Git LFS客户端从官网下载。在项目根目录运行git lfs install初始化。指定要跟踪的文件类型。创建一个名为.gitattributes的文件或编辑已有的添加规则例如# 跟踪所有fbx和blend文件 *.fbx filterlfs difflfs mergelfs -text *.blend filterlfs difflfs mergelfs -text # 跟踪所有超过10MB的wav文件 *.wav filterlfs difflfs mergelfs -text像往常一样git add .gitattributes和git add你的资源文件然后提交推送。注意Github对LFS有流量和存储限制免费账户每月有1GB的带宽和1GB的存储。对于超大型项目可能需要购买额度。7.2 合并冲突的解决尤其是场景和预制体当多人修改了同一个场景.unity或预制体.prefab文件并尝试合并时会发生冲突。因为即使它们是文本格式YAML其结构也非常复杂自动合并几乎总会出错。最佳实践是建立团队规则场景分工如果可能将一个大场景拆分为多个小的子场景Additive Loading或者为不同功能的开发者分配不同的场景文件。预制体编辑锁使用一些团队协作工具如Unity的Collaborate服务或第三方工具Plastic SCM提供的“文件锁定”功能防止多人同时编辑同一个预制体。手动合并当冲突不可避免时需要手动解决。不要直接接受“ours”或“theirs”。步骤备份冲突文件。在Unity编辑器中分别打开“我们的”版本和“他们的”版本可以通过临时切换分支实现。仔细对比两个版本中游戏对象层级Hierarchy和组件属性的差异。在文本编辑器中打开冲突的.unity或.prefab文件找到标记的冲突区块根据你在编辑器中观察到的差异手动编辑YAML文本保留正确的部分删除冲突标记。这是一个繁琐且容易出错的过程所以预防清晰的模块划分和沟通远比治疗重要。7.3 忽略规则不生效检查Git缓存如果你发现Library文件夹里的文件仍然出现在git status中即使.gitignore规则正确很可能是因为它们已经被Git跟踪了。如前所述使用git rm -r --cached Library命令将其从Git跟踪中移除但保留在本地磁盘然后重新提交。7.4 仓库体积依然过大使用BFG或git filter-branch清理历史如果历史提交中不小心引入了大文件比如一个巨大的.zip备份包即使后续的提交中删除了它这个文件仍然存在于Git的历史记录中会持续占用仓库空间。要彻底清理需要使用git filter-branch或更易用的工具如BFG Repo-Cleaner。这是一个高风险操作因为它会重写提交历史。在执行前务必确保所有协作者都已将他们的工作推送或备份因为重写历史后他们的本地历史将与远程不兼容需要强制拉取git pull --force或重新克隆。我个人更倾向于在项目早期就建立好规范的.gitignore和提交习惯避免将垃圾文件纳入版本控制这比事后清理要简单和安全得多。