下面这份手册以“尽快进入真实 Unity 项目并使用 AI 开发”为目标，不要求你先系统学习游戏开发理论。 后台开发者的 Unity Vibe Coding Onboarding 手册 版本：v1.0 适用对象：具备 Java、C#、Go、Python、Node.js 等后台开发经验，但没有 Unity 开发经验的工程师 目标：在 2～4 周内，能够借助 Codex、Claude Code、Cursor 等 AI 编程工具，在现有 Unity 项目中完成小型功能、Bug 修复、接口接入和自动化测试 ⸻ 一、你真正需要掌握什么 进入 Unity 项目时，不需要先成为游戏开发专家。 第一阶段只需要具备以下能力： 能在本地打开并运行 Unity 项目。 能理解 Scene、GameObject、Component、Prefab、MonoBehaviour。 能找到一个界面或功能对应的脚本。 能修改 C# 代码并验证效果。 能看懂 Unity Console 中的报错。 能让 AI 在有限范围内修改项目。 能避免 AI 破坏 Prefab、Scene 和序列化数据。 能为修改补充基础测试和验证步骤。 可以把 Unity 项目理解为： C# 业务代码 + 可视化对象树 + 序列化配置 + 资源文件 + 游戏运行时。 后台工程师最容易犯的错误，是只关注 C# 代码，忽略 Unity 编辑器里的对象、组件和序列化引用。 ⸻ 二、Unity 和后台系统的思维映射 后台开发概念 Unity 中对应概念 应用进程 Unity Player 服务启动入口 首个 Scene 服务实例 GameObject 依赖组件 Component Controller MonoBehaviour / Presenter 配置文件 ScriptableObject / JSON / Inspector 字段 数据库实体 数据模型、存档对象 API Client 网络请求模块 路由 Scene 切换、UI 页面导航 定时任务 Update、Coroutine、Timer 服务容器 GameObject 层级或 DI 容器 模板 Prefab 测试环境 Play Mode 单元测试 Edit Mode Test 集成测试 Play Mode Test 日志 Debug.Log / Console 部署产物 Build 静态资源 Assets 包管理器 Unity Package Manager 最重要的区别是： 后台服务主要由代码构成。 Unity 功能通常由以下部分共同构成： C# 脚本 Scene 中的对象 Prefab Inspector 参数 图片、动画、材质、音频 对象之间的序列化引用 所以，“代码编译通过”不代表功能正确。 ⸻ 三、开发环境准备 3.1 必备工具 建议安装： Unity Hub 项目要求的 Unity Editor 版本 Git Rider、Visual Studio 或 VS Code 一个支持仓库级分析的 AI 编程工具 Git LFS 项目所需的 Android SDK、Xcode 或其他构建工具 优先使用项目指定的 Unity 版本，不要自行升级。 Unity 项目对编辑器版本、Package 版本和资源序列化格式比较敏感。即使只差一个小版本，也可能出现： Package 不兼容 Shader 编译错误 Prefab 被重新序列化 Scene 出现大面积无意义修改 Android 或 iOS 构建失败 Unity 版本通常可以在下面的文件中查看： ProjectSettings/ProjectVersion.txt 3.2 第一次打开项目 建议按照以下顺序操作： 克隆项目仓库。 安装 Git LFS。 执行 git lfs pull。 在 Unity Hub 中选择项目指定版本。 使用 Unity Hub 打开项目。 等待资源导入完成。 查看 Console 是否存在错误。 找到项目的启动 Scene。 点击 Play。 不做任何修改，先确认基线能够运行。 第一次打开大型项目时，资源导入可能产生大量本地缓存。 这些目录通常不应该提交： Library/ Temp/ Logs/ Obj/ Build/ Builds/ UserSettings/ 具体以项目的 .gitignore 为准。 3.3 第一次提交前检查 执行： git status 确认没有因为打开 Unity 而产生大量无关修改。 如果出现大量 .prefab、.unity、.asset 文件变化，先不要提交。 常见原因包括： Unity 版本不一致 项目序列化设置不同 Meta 文件缺失 Package 自动升级 平台切换导致资源重新导入 ⸻ 四、Unity 项目的核心目录 一个典型 Unity 项目包含： ProjectRoot/ ├── Assets/ ├── Packages/ ├── ProjectSettings/ ├── Library/ ├── Logs/ ├── Temp/ └── UserSettings/ 4.1 Assets 绝大部分业务代码和游戏资源都在这里。 常见结构： Assets/ ├── Scripts/ │ ├── Runtime/ │ ├── Editor/ │ ├── UI/ │ ├── Network/ │ ├── Models/ │ └── Tests/ ├── Scenes/ ├── Prefabs/ ├── Art/ ├── Audio/ ├── Materials/ ├── Resources/ ├── StreamingAssets/ └── Plugins/ 项目不一定采用以上结构，应优先遵循原项目约定。 4.2 Packages Unity 的包依赖。 重要文件： Packages/manifest.json Packages/packages-lock.json 它们类似： npm 的 package.json Maven 的 pom.xml Go 的 go.mod 不要让 AI 随意修改 Package 版本。 4.3 ProjectSettings 项目级配置，例如： 输入设置 渲染设置 Player Settings Tag 和 Layer 构建设置 物理系统设置 这些文件通常是文本，但修改风险较高。 4.4 Library Unity 自动生成的缓存。 不应提交，也不应让 AI 分析整个目录。 将 Library 排除在 AI 索引之外，可以显著减少噪声。 ⸻ 五、五个最重要的 Unity 概念 5.1 Scene Scene 是一个运行场景。 可以把它理解成： 一个页面 一个关卡 一个启动环境 一组已经配置好的对象 Scene 文件后缀： .unity 一个项目可能包含： 启动 Scene 登录 Scene 大厅 Scene 战斗 Scene 测试 Scene Scene 之间可以进行加载和切换。 5.2 GameObject GameObject 是 Unity 中最基础的对象容器。 它本身通常没有复杂功能，功能由 Component 提供。 例如一个登录按钮可能是： LoginButton ├── RectTransform ├── Image ├── Button └── LoginButtonView 这里的 LoginButton 是 GameObject，下面这些是组件。 5.3 Component Component 是挂载在 GameObject 上的功能模块。 常见组件： Transform RectTransform Camera Canvas Image Text Button Animator AudioSource 自定义 MonoBehaviour 这种设计是组合，而不是深层继承。 5.4 Prefab Prefab 是可复用的对象模板。 可以类比为： UI 组件模板 对象原型 带默认配置的依赖组合 可实例化的对象定义 例如： UserItem.prefab Dialog.prefab Enemy.prefab RewardPopup.prefab 修改 Prefab 可能影响所有实例。 需要区分： Prefab Asset Prefab Instance Prefab Variant Override AI 很难可靠地直接编辑复杂 Prefab，因此第一阶段应尽量通过代码修改，而不是让 AI 大规模修改 Prefab YAML。 5.5 MonoBehaviour MonoBehaviour 是最常见的 Unity 脚本基类。 using UnityEngine; public sealed class HealthView : MonoBehaviour { [SerializeField] private int maxHealth = 100; private int _currentHealth; private void Awake() { _currentHealth = maxHealth; } public void TakeDamage(int damage) { _currentHealth = Mathf.Max(0, _currentHealth - damage); } } 脚本通常需要挂在 GameObject 上，才会参与 Unity 生命周期。 ⸻ 六、MonoBehaviour 生命周期 这是后台开发者必须优先理解的部分。 常见生命周期： Awake OnEnable Start Update LateUpdate OnDisable OnDestroy 6.1 Awake 对象被加载时执行，适合： 初始化内部状态 获取自身组件 建立不依赖其他对象启动顺序的状态 private void Awake() { _button = GetComponent(); } 6.2 OnEnable 对象每次被启用时执行。 适合： 订阅事件 注册回调 启动临时任务 private void OnEnable() { _eventBus.UserUpdated += HandleUserUpdated; } 6.3 Start 通常在第一次 Update 前执行。 适合： 依赖其他对象已经完成 Awake 的初始化 启动页面逻辑 首次刷新 UI 6.4 Update 每帧调用一次。 private void Update() { } 不要在 Update 中进行： 网络请求 文件 IO 大量对象查找 高频内存分配 每帧 LINQ 每帧 JSON 序列化 每帧创建新集合 后台开发者可以把 Update 理解为一个每秒调用 30～120 次的超高频循环。 6.5 OnDisable 对象被禁用时调用。 适合： 取消事件订阅 停止临时任务 清理页面状态 6.6 OnDestroy 对象被销毁时调用。 适合： 释放资源 取消异步操作 注销全局事件 推荐保持订阅和取消订阅成对出现： private void OnEnable() { _service.Changed += HandleChanged; } private void OnDisable() { _service.Changed -= HandleChanged; } ⸻ 七、Unity Inspector 和序列化 Unity 可以把字段显示在 Inspector 中。 public sealed class LoginView : MonoBehaviour { [SerializeField] private Button loginButton; [SerializeField] private TMP_InputField usernameInput; } 这些字段通常由编辑器拖拽绑定。 即使代码编译通过，如果 Inspector 没有绑定对象，也可能出现： NullReferenceException 7.1 Unity 常见序列化规则 通常可以序列化： public 字段 带 [SerializeField] 的 private 字段 Unity 支持的基础类型 可序列化类型 UnityEngine.Object 引用 通常不直接序列化： 属性 Dictionary 接口 普通多态对象 静态字段 推荐： [SerializeField] private Button submitButton; 不推荐： public Button submitButton; 原因是 private 字段可以减少外部随意修改。 7.2 重命名字段的风险 假设原字段是： [SerializeField] private Button loginButton; 直接改成： [SerializeField] private Button submitButton; 可能导致原有 Inspector 引用丢失。 安全写法： using UnityEngine.Serialization; [FormerlySerializedAs("loginButton")] [SerializeField] private Button submitButton; AI 修改序列化字段名称前，必须检查是否需要 FormerlySerializedAs。 ⸻ 八、理解 Unity UI 常见 UI 层级： Canvas └── LoginPanel ├── Title ├── UsernameInput ├── PasswordInput └── LoginButton 常用组件： Canvas RectTransform Image TextMeshProUGUI Button Toggle ScrollRect InputField LayoutGroup 8.1 UI 代码的推荐分层 不要把请求、状态、业务规则和视图操作全部放进一个 MonoBehaviour。 推荐： LoginView LoginPresenter LoginService LoginRequest LoginResponse 示例： public interface ILoginView { string Username { get; } string Password { get; } void SetLoading(bool loading); void ShowError(string message); void ShowSuccess(); } public sealed class LoginPresenter { private readonly ILoginView _view; private readonly ILoginService _service; public LoginPresenter(ILoginView view, ILoginService service) { _view = view; _service = service; } public async Task LoginAsync(CancellationToken cancellationToken) { _view.SetLoading(true); try { await _service.LoginAsync( _view.Username, _view.Password, cancellationToken); _view.ShowSuccess(); } catch (OperationCanceledException) { } catch (Exception exception) { _view.ShowError(exception.Message); } finally { _view.SetLoading(false); } } } 这种结构对后台开发者更友好，也更适合 AI 生成和测试。 ⸻ 九、Unity 中的依赖管理 Unity 项目中常见以下方式： 9.1 Inspector 注入 [SerializeField] private UserPanel userPanel; 优点： 简单 可视化 适合资源对象 缺点： 运行前才能发现漏绑 依赖关系隐藏在 Scene 和 Prefab 中 9.2 GetComponent private void Awake() { _button = GetComponent(); } 适合获取同一 GameObject 上的组件。 可以配合： [RequireComponent(typeof(Button))] public sealed class SubmitButton : MonoBehaviour { } 9.3 构造函数注入 普通 C# 类可以使用： public sealed class InventoryService { private readonly IInventoryRepository _repository; public InventoryService(IInventoryRepository repository) { _repository = repository; } } MonoBehaviour 不应该依赖普通构造函数进行初始化。 9.4 DI 框架 一些项目会使用： VContainer Zenject / Extenject 自研 Service Locator 自研 Context 不要在不了解原架构时自行引入新的 DI 框架。 ⸻ 十、Unity 中的异步编程 Unity 中常见四种异步方式： Coroutine Task UniTask 回调 10.1 Coroutine private IEnumerator LoadData() { yield return new WaitForSeconds(1f); Debug.Log("Loaded"); } Coroutine 不是线程，只是由 Unity 主循环调度的状态机。 10.2 Task 普通 C# 逻辑可以使用 Task。 但需要注意： Unity API 大多数只能在主线程调用。 对象可能在 await 期间被销毁。 页面可能已经关闭。 Scene 可能已经切换。 CancellationToken 必须正确传递。 10.3 UniTask 很多大型 Unity 项目使用 UniTask。 示例： private async UniTaskVoid Start() { await LoadAsync(this.GetCancellationTokenOnDestroy()); } 不要默认项目安装了 UniTask，应先检查 Packages 和项目代码。 10.4 页面关闭后的异步回调 常见 Bug： 用户打开弹窗。 弹窗开始异步加载。 用户关闭弹窗。 异步加载结束。 回调再次显示弹窗。 推荐使用取消令牌： public sealed class ItemPopup : MonoBehaviour { private CancellationTokenSource _loadCts; private void OnEnable() { _loadCts = new CancellationTokenSource(); LoadAsync(_loadCts.Token).Forget(); } private void OnDisable() { _loadCts?.Cancel(); _loadCts?.Dispose(); _loadCts = null; } private async UniTaskVoid LoadAsync(CancellationToken cancellationToken) { var data = await LoadDataAsync(cancellationToken); cancellationToken.ThrowIfCancellationRequested(); Render(data); } } AI 生成异步代码时，重点检查： 是否支持取消 是否在对象销毁后继续访问对象 是否吞掉异常 是否有重复请求 是否有竞态条件 是否有多次点击导致的重入 ⸻ 十一、网络请求与后台接口接入 作为后台开发者，你可能最先负责 API 接入。 Unity 项目常见网络方案： UnityWebRequest HttpClient BestHTTP 自研网络层 Protobuf WebSocket TCP 长连接 不要绕过项目原有网络层直接写新的 HttpClient。 先搜索： ApiClient HttpClient UnityWebRequest RequestManager NetworkManager SendRequest BaseRequest 11.1 接口接入标准流程 找到项目已有网络入口。 找到已有相似接口。 复制其调用结构。 定义请求 DTO。 定义响应 DTO。 处理错误码。 处理超时和取消。 将 DTO 转换为领域模型。 更新 UI。 补充 Mock 或测试。 11.2 不要直接信任后台数据 后台数据进入 Unity 后要考虑： 字段缺失 空数组 空字符串 时间格式不一致 旧客户端缺少新字段 枚举出现未知值 图片 URL 无效 数值超出 UI 范围 网络返回晚于页面生命周期 推荐 DTO 和运行时模型分离： public sealed class UserResponseDto { public string id; public string nickname; public int level; } public sealed class UserProfile { public string Id { get; } public string Nickname { get; } public int Level { get; } public UserProfile(string id, string nickname, int level) { Id = id; Nickname = string.IsNullOrWhiteSpace(nickname) ? "Unknown" : nickname; Level = Math.Max(0, level); } } ⸻ 十二、资源和内存的基本概念 Unity 不只是托管内存。 资源可能存在于： C# 托管堆 Unity Native 内存 GPU 显存 音频内存 AssetBundle Addressables 缓存 Destroy 一个 GameObject，不一定立即释放其关联资源。 常见资源系统： Resources AssetBundle Addressables 自研资源管理器 第一阶段不要自行改变资源加载方式。 搜索： Addressables.LoadAssetAsync Resources.Load AssetBundle ResourceManager AssetManager LoadPrefab InstantiateAsync 12.1 常见资源泄漏 加载后未释放 Handle 事件未取消订阅 静态集合持有对象 缓存无限增长 RenderTexture 未释放 Texture 或 Mesh 运行时创建后未销毁 对象池归还失败 Scene 切换后仍持有旧对象 ⸻ 十三、Unity 的测试体系 Unity Test Framework 主要包含： Edit Mode Tests Play Mode Tests 13.1 Edit Mode Tests 适合： 普通 C# 类 领域规则 数据转换 数值计算 Presenter 状态机 配置校验 示例： using NUnit.Framework; public sealed class HealthTests { [Test] public void TakeDamage_ShouldNotGoBelowZero() { var health = new Health(100); health.TakeDamage(120); Assert.AreEqual(0, health.Current); } } 13.2 Play Mode Tests 适合： GameObject 生命周期 MonoBehaviour Scene Prefab UI 交互 Coroutine 与 Unity Runtime 相关的功能 示例： using System.Collections; using NUnit.Framework; using UnityEngine; using UnityEngine.TestTools; public sealed class HealthViewTests { [UnityTest] public IEnumerator Awake_ShouldInitializeHealth() { var gameObject = new GameObject(); var view = gameObject.AddComponent(); yield return null; Assert.IsNotNull(view); Object.Destroy(gameObject); } } 13.3 Vibe Coding 的测试策略 AI 最适合生成和维护普通 C# 逻辑。 因此要主动把逻辑从 MonoBehaviour 中提取出来： MonoBehaviour：生命周期和 Unity 对象引用 Presenter：流程协调 Service：业务操作 Model：状态和规则 Adapter：Unity API 或第三方 SDK 这样可以让大部分代码在 Edit Mode 中测试。 ⸻ 十四、如何阅读一个陌生 Unity 项目 不要从所有代码开始阅读。 按下面的顺序建立地图。 14.1 找到启动入口 查看： File → Build Settings 找到第一个 Scene。 然后搜索： Bootstrap Launcher GameEntry AppEntry Main Initialize Startup 14.2 找到核心管理器 搜索： GameManager UIManager SceneManager NetworkManager AudioManager ResourceManager ConfigManager EventManager 不要假设所有 Manager 都是合理设计。先理解其职责。 14.3 找到一个完整功能链 例如“用户点击登录”： Button → View → Presenter / Controller → LoginService → Network Client → Response → User Model → UI 更新 选择一个简单功能追踪，比阅读所有架构文档更有效。 14.4 画项目地图 建议建立： docs/onboarding/ ├── architecture-overview.md ├── startup-flow.md ├── ui-navigation.md ├── network-flow.md ├── resource-loading.md ├── save-system.md └── glossary.md 每理解一个模块就让 AI 更新文档。 文档必须带源码路径，例如： 登录入口： Assets/Scripts/Login/LoginView.cs 网络调用： Assets/Scripts/Network/ApiClient.cs ⸻ 十五、Unity Vibe Coding 的正确工作方式 不要直接对 AI 说： 帮我实现一个登录功能。 应该采用小范围、可验证、上下文明确的任务。 15.1 标准工作循环 理解任务 → 搜索相似实现 → 建立影响范围 → 让 AI 给方案 → 人工审核方案 → 小步修改 → 编译 → 运行测试 → Unity 手动验证 → 检查 Git Diff → 提交 15.2 每个任务限制修改范围 推荐在提示词中明确： 本次只允许修改： Assets/Scripts/Login/LoginPresenter.cs Assets/Scripts/Login/LoginService.cs Assets/Tests/EditMode/LoginPresenterTests.cs 不得修改： Scene Prefab ProjectSettings Packages 第三方插件 15.3 先分析，后修改 推荐提示词： 先不要修改代码。 请分析这个 Unity 项目中的登录流程，并输出： 登录按钮对应的 View。 登录请求经过的主要类。 请求和响应 DTO。 成功后的状态更新位置。 可能的生命周期和异步风险。 完成需求最小需要修改的文件。 推荐的验证步骤。 所有结论必须附带文件路径和关键类名。 15.4 修改前要求 AI 搜索相似实现 在实现之前，先搜索项目中三个最接近的现有功能。 优先沿用现有项目的： 命名规范 网络请求方式 异步方式 错误处理方式 日志方式 UI 更新方式 测试结构 不要引入新的框架或模式。 ⸻ 十六、推荐的 AI 项目规则 可以在仓库中建立 AGENTS.md： # Unity Project Agent Rules ## Unity Version 必须使用 ProjectSettings/ProjectVersion.txt 中指定的 Unity 版本。 ## General Rules 优先沿用现有架构。 不要自行升级 Package。 不要修改 Library、Temp、Logs、Obj。 不要提交生成的构建产物。 不要在未说明的情况下引入第三方依赖。 修改前先搜索相似实现。 每次修改控制在最小范围。 对不确定的架构结论明确标注。 不要通过猜测创建不存在的 API。 ## Unity Asset Safety 除非任务明确要求，否则不得直接修改： .unity .prefab .asset .controller .anim .mat ProjectSettings Packages 不得删除或重新生成 .meta 文件。 移动资源时必须同时移动对应 .meta 文件。 ## Serialization Safety 修改 [SerializeField] 字段名时检查 FormerlySerializedAs。 不要随意改变序列化字段类型。 不要将已有序列化字段从实例字段改为静态字段。 不要假设 Inspector 引用一定存在。 新增必要引用时提供编辑器配置说明。 ## Runtime Safety 不要在 Update 中执行高开销操作。 异步操作必须考虑取消、销毁和 Scene 切换。 事件订阅和取消订阅必须成对。 UnityEngine.Object 的使用必须考虑对象已经被销毁。 Unity API 默认只能在主线程调用。 ## Testing 业务逻辑优先放在普通 C# 类中。 普通逻辑优先补 Edit Mode Test。 生命周期和 Scene 行为使用 Play Mode Test。 修改后给出自动测试和手动验证步骤。 ## Completion Format 完成任务后输出： 修改文件。 核心设计。 风险点。 自动测试。 Unity 编辑器验证步骤。 未完成或无法验证的部分。 ⸻ 十七、适合后台开发者的代码架构 推荐采用“薄 MonoBehaviour”原则。 不推荐 public sealed class ShopPanel : MonoBehaviour { // UI // 网络请求 // 商品规则 // 支付逻辑 // JSON 解析 // 缓存 // 埋点 // 动画 // 错误提示 } 推荐 ShopPanelView ShopPresenter ShopService ShopRepository ShopItem PurchasePolicy ShopApiClient MonoBehaviour 只负责： 获取 Unity 生命周期 持有 Unity 对象引用 转发按钮事件 渲染 UI 启动或取消 Presenter 核心逻辑放在普通 C# 类中。 这样做有四个优势： 后台开发者更容易理解。 AI 更容易准确修改。 单元测试更容易编写。 Unity 生命周期风险更小。 ⸻ 十八、Unity 中最常见的 AI 误操作 18.1 直接编辑 Prefab YAML Prefab 和 Scene 本质上是序列化文件，但不适合让 AI 大规模手写。 风险： fileID 错误 引用丢失 层级错乱 Override 破坏 Unity 打开后重新序列化 Merge 冲突 更安全的方式： 使用 Unity Editor 手工操作 编写一次性 Editor Script 通过现有 Prefab 实例进行配置 只让 AI 输出操作说明 18.2 删除 Meta 文件 Unity 使用 .meta 中的 GUID 标识资源。 删除 Meta 文件可能导致： Prefab 引用丢失 材质丢失 脚本 Missing Scene 引用断裂 资源文件和 Meta 文件必须作为一个整体移动。 18.3 自行升级 Package AI 可能为了使用一个 API，直接升级 Package。 这可能造成整个项目不可运行。 原则： 优先使用当前版本已经存在的 API。 18.4 在 Update 中写后台式轮询 错误示例： private void Update() { RefreshUserData(); } 这可能每秒发出几十次请求。 18.5 忽略对象生命周期 错误示例： private async void Load() { var data = await _service.LoadAsync(); title.text = data.Title; } await 返回时 title 所属对象可能已经销毁。 18.6 混用多个异步体系 同一个模块中不要无理由混用： Coroutine Task UniTask 回调 应跟随项目现有约定。 18.7 引入过度抽象 AI 容易为一个简单按钮创建： CommandBus EventAggregator Repository Factory Strategy StateMachine 除非项目本身采用这些模式，否则优先最小实现。 ⸻ 十九、Bug 定位方法 Unity Bug 可以按四层定位。 第一层：编译错误 查看 Console 中的红色错误。 优先处理第一个编译错误，因为后续错误可能是连锁反应。 第二层：运行时异常 常见错误： NullReferenceException MissingReferenceException IndexOutOfRangeException ArgumentException 重点查看： 完整堆栈 第一个属于业务代码的调用位置 对象是否由 Inspector 绑定 对象是否已销毁 生命周期是否正确 第三层：配置和资源问题 表现： 没有报错但界面不显示 点击无反应 图片为空 Prefab 实例不正确 动画不播放 检查： GameObject 是否 Active Component 是否 Enabled Canvas 层级 Inspector 引用 Sorting Order Layer Prefab Override 资源地址 第四层：状态和时序问题 表现： 偶现 快速点击才出现 切换页面后出现 网络慢时出现 第二次打开才出现 通常涉及： 异步竞态 重复订阅 状态未重置 对象池残留 请求返回顺序 Scene 切换 ⸻ 二十、Git 和 Unity 协作规范 20.1 小提交 一个提交尽量只做一件事。 例如： fix(login): cancel pending login when panel closes 不要混入： 无关格式化 Scene 重存 Package 更新 资源重新导入 大范围重命名 20.2 检查 Diff 每次提交前检查： git diff --stat git diff git status 重点关注： 是否出现大量 .unity 修改 是否出现大量 .prefab 修改 是否修改 .meta 是否修改 Packages 是否包含 Library 是否发生整文件换行变化 20.3 Scene 和 Prefab 冲突 Scene 和 Prefab 冲突通常比普通代码冲突难处理。 降低冲突的方法： 一个任务尽量只修改少量 Prefab 不要多人同时修改同一个 Scene 将大 Scene 拆分 使用 Prefab 管理局部对象 程序功能尽量通过代码和独立配置完成 ⸻ 二十一、第一周学习任务 Day 1：运行项目 完成： 安装正确 Unity 版本 打开项目 找到启动 Scene 运行项目 查看 Console 找到 Build Settings 确认 Git 没有异常修改 产出： docs/onboarding/local-setup.md Day 2：理解对象模型 完成： 创建测试 Scene 创建 GameObject 添加 Component 编写 MonoBehaviour 理解 Inspector 修改 [SerializeField] 字段 点击 Play 验证生命周期 练习： public sealed class LifecycleLogger : MonoBehaviour { private void Awake() { Debug.Log("Awake"); } private void OnEnable() { Debug.Log("OnEnable"); } private void Start() { Debug.Log("Start"); } private void OnDisable() { Debug.Log("OnDisable"); } private void OnDestroy() { Debug.Log("OnDestroy"); } } Day 3：完成一个 UI 功能 创建： 输入框 按钮 文本 点击按钮更新文本 目标： 理解 UI 对象、事件和脚本引用。 Day 4：接口调用 完成： 找到项目网络层 Mock 一个接口 发起请求 显示加载状态 处理成功和失败 页面关闭时取消请求 Day 5：测试 完成： 创建 Edit Mode Test 测试一个普通 C# 类 创建 Play Mode Test 测试一个简单 MonoBehaviour Day 6：阅读真实功能 选择一个小功能，输出： 用户操作入口 主要类 数据流 Scene 或 Prefab 网络请求 状态更新 风险点 Day 7：完成第一个真实任务 适合任务： 修改文案 新增输入校验 修复按钮重复点击 增加请求超时 修复事件重复订阅 增加空数据处理 增加一个埋点 增加一个 Edit Mode Test ⸻ 二十二、第二到第四周计划 第二周：具备独立修改能力 重点： UI 页面结构 项目网络层 异步和生命周期 Prefab 基础 日志和错误定位 Edit Mode Tests 目标： 独立完成低风险 Bug。 第三周：理解项目架构 重点： 启动流程 Scene 流程 UI 导航 资源加载 配置系统 用户状态 存档系统 事件系统 目标： 可以判断需求应该放在哪个模块。 第四周：建立 Vibe Coding Loop 重点： AGENTS.md 自动代码检查 自动测试 项目地图 AI 任务模板 Git Diff 审查 手动测试清单 失败回滚流程 目标： 让 AI 稳定完成小型需求，而不是每次都从零解释项目。 ⸻ 二十三、常用 Vibe Coding 提示词 23.1 分析功能 你正在分析一个 Unity 项目。 任务：分析“用户点击领取奖励”功能的完整调用链。 请输出： UI 按钮所在的 View、Prefab 和 Scene。 点击事件绑定方式。 Presenter 或 Controller。 网络请求入口。 请求和响应 DTO。 用户数据更新位置。 UI 刷新位置。 埋点和日志。 异步、生命周期、重复点击风险。 相关测试。 所有结论必须附带文件路径。 不确定的内容必须标注为推测。 暂时不要修改代码。 23.2 实现小功能 任务：登录按钮点击后，在请求完成前禁止重复点击。 要求： 先搜索项目中相似的防重复点击实现。 沿用现有异步方案。 不修改 Prefab 和 Scene。 不引入第三方依赖。 页面关闭后必须取消未完成请求。 请求成功、失败、取消后都必须恢复正确状态。 为核心状态逻辑补充 Edit Mode Test。 修改范围尽量小。 开始前先给出： 相关文件。 实现方案。 风险点。 计划修改范围。 确认方案合理后再修改代码。 23.3 审查 AI 修改 请对当前 Git Diff 做对抗性审查。 重点检查： Unity 生命周期错误 异步取消 对象销毁后访问 事件重复订阅 Inspector 序列化兼容性 主线程限制 Update 中的性能问题 GC Alloc Prefab 或 Scene 意外修改 Meta 文件变化 Package 版本变化 缺少测试 缺少错误处理 与项目现有架构不一致 按严重程度输出： Blocker、High、Medium、Low。 不要直接修改代码。 23.4 生成验证清单 根据当前修改生成 Unity 验证清单。 至少覆盖： 正常流程 网络失败 网络超时 快速重复点击 页面关闭 Scene 切换 空数据 异常数据 第二次打开页面 Android 或 iOS 平台差异 每个测试项包含： 前置条件、操作步骤、预期结果、需要观察的日志。 ⸻ 二十四、首批推荐任务 适合 Unity 新人的任务： 修改纯 C# 数据规则 新增参数校验 接入简单 HTTP 接口 修复空引用 修复重复点击 增加错误提示 增加取消机制 增加日志 增加 Edit Mode Test 编写项目文档 增加 Editor 校验工具 编写配置检查脚本 暂时不建议独立承担： 渲染管线升级 Shader 开发 动画系统重构 复杂资源系统修改 Addressables 迁移 大规模 Scene 重构 大型 Prefab 重构 移动端性能专项 原生 iOS 或 Android 插件 多线程 Job System ECS / DOTS 大规模 Unity 版本升级 ⸻ 二十五、Unity 开发完成定义 一个任务不能只以“代码写完”为完成。 建议 Definition of Done： 代码可以编译。 Unity Console 无新增错误。 自动测试通过。 正常流程手动验证通过。 异常流程已验证。 快速操作不会触发竞态。 页面关闭后没有残留任务。 没有意外 Scene 或 Prefab 修改。 没有 Meta 文件丢失。 没有 Package 版本变化。 Git Diff 范围合理。 新增 Inspector 字段有配置说明。 关键行为有日志。 文档已更新。 已说明未验证的平台和风险。 ⸻ 二十六、后台开发者需要转变的五个习惯 习惯一：从“代码调用链”转向“代码 + 对象 + 资源调用链” 一个功能可能不是从代码入口开始，而是从 Scene 中一个按钮的 Inspector 事件开始。 习惯二：把生命周期当成核心业务约束 对象会被启用、禁用、销毁、复用，不能假设服务实例一直存在。 习惯三：任何异步操作都考虑页面已经不存在 这是 Unity UI 最常见的问题之一。 习惯四：每次修改都检查序列化影响 字段重命名、类型变化和资源移动都可能破坏已有数据。 习惯五：让 AI 修改小范围，而不是“接管整个项目” AI 在以下情况下最可靠： 上下文明确 文件范围有限 有相似实现 有测试 有明确禁止项 有人工验证步骤 ⸻ 二十七、最终能力检查表 完成 Onboarding 后，你应该能够回答： 项目使用哪个 Unity 版本？ 项目从哪个 Scene 启动？ 核心启动类在哪里？ UI 页面如何创建和关闭？ Prefab 如何加载？ 网络请求从哪里发出？ 项目使用 Task、Coroutine 还是 UniTask？ 用户数据保存在哪里？ 全局事件如何注册和取消？ 一个页面关闭后，异步任务如何取消？ Edit Mode Test 如何运行？ Play Mode Test 如何运行？ 哪些文件不能让 AI 直接修改？ 如何判断一次 Git Diff 是否安全？ 如何完成一次 Android 或 iOS 构建？ 新增序列化字段后如何配置？ 如何定位 MissingReferenceException？ 如何避免按钮重复点击？ 如何为普通 C# 业务逻辑编写测试？ 如何向 AI 描述一个小型 Unity 任务？ 当这些问题大部分都能回答时，你已经具备进入真实 Unity 项目进行 Vibe Coding 的基础能力。 ⸻ 结语 后台开发者进入 Unity 的最大优势，不是熟悉图形和动画，而是已经具备： 模块化能力 接口设计能力 数据建模能力 异步编程经验 自动化测试意识 日志和监控意识 分布式系统中的异常思维 需要补上的主要是： Unity 对象模型 生命周期 Inspector 序列化 Scene 和 Prefab 主线程限制 资源生命周期 编辑器操作 客户端状态和时序 最有效的学习方式不是连续看几十小时课程，而是： 运行一个真实项目，选择一个足够小的功能，追踪完整链路，用 AI 帮助理解和修改，再通过测试、Unity 编辑器和 Git Diff 三重验证。 你的第一个目标不是“学会 Unity”。 而是： 能够在不破坏项目的前提下，稳定完成第一个真实需求。 这份内容可以直接作为团队仓库里的 docs/unity-onboarding.md。后续最值得补充的是针对你们实际项目的启动流程、目录结构、网络层、UI 框架和资源系统。