如何把Built-in迁移到URP又不炸画面？skills之migrate-birp-to-urp技能五阶段迁移流程全解

在 Unity 项目中把 Built-in Render Pipeline 迁移到 URP（Universal Render Pipeline），是很多开发者绕不开的大难题：材质变粉色、画面过曝、烘焙光照全乱……开源项目skills是面向 AI 编码 Agent 的可复用技能集合，其中 migrate-birp-to-urp 技能专门负责 Built-in 到 URP 的渲染管线迁移：它内置五阶段安全流程 + 成功门禁，帮你把"迁移不炸画面"变成一套可执行的检查清单。

为什么直接换管线容易"炸画面" 🧨

很多人以为迁移就是"安装 URP → 点一下转换器"，但实际风险藏在细节里：

• 转换是单向的：Render Pipeline Converter 一旦运行就难以撤销，没有备份等于裸奔
• 质量档位会"掉链子"：Graphics 设置切了 URP，Quality 档位却可能没跟上
• PPv2 后期处理会叠加：旧的 PostProcessVolume 没关，加上新的 URP Volume，画面直接过曝
• 烘焙光照不是"编译通过"就对了：旧 lightmap 和反射探针在 URP 下可能失真
• 工具日志会"说谎"：日志说"已添加 Bloom"，实际保存的 VolumeProfile 却是空的

migrate-birp-to-urp 技能的核心设计正是针对这些坑：先检查、再确认回滚点、分阶段推进、每一阶段都基于保存后的真实项目状态来验证。

安装 skills，一分钟接入你的 AI Agent 🚀

skills 兼容 Claude Code、Cursor、Cline、GitHub Copilot 等 50+ Agent，安装只需一行命令：

npx skills add Unity-Technologies/skills

也可以直接克隆仓库查看技能实现：

git clone https://gitcode.com/gh_mirrors/skills54/skills

安装后，当你用自然语言说"把项目迁移到 URP"，Agent 会自动激活对应技能。技能通过 Unity CLI 在打开的 Editor 中执行 C#，自动检测管线状态、运行转换器、验证保存结果——详细安全机制见 SECURITY.md。

五阶段迁移流程全解 🗺️

技能的完整阶段模型定义在 references/migration-workflow.md 中：

每阶段结束都会给出诚实的状态汇报：Completed/Incomplete/Manual follow-up+ 下一阶段是什么，而不是笼统一句"迁移完成"。

Phase 0：检查与规划（安全门禁）🔍

• 检测当前管线：Built-in、半迁移、已 URP 还是 HDRP（本技能只负责 Built-in → URP）
• 盘点风险面：PPv2、烘焙光照/lightmap、反射探针、粒子/雾/烟材质、植被材质、多 Quality 档位、自定义 shader（#pragma surface、GrabPass等）
• ⚠️安全门禁：未确认备份、分支或可丢弃副本之前，绝不安装 URP 或分配 URP Asset——因为分配后材质会立刻变粉色，直到材质转换完成

Phase 1：URP 安装与材质转换 📦

• 安装 URP 会触发包刷新、编译和域重载，技能将其视为"阶段边界"，重载后从断点继续，而不是从头再来
• 创建 URP Asset + Renderer Asset，并分配到 Graphics 设置和每个相关 Quality 档位（只分配 Graphics 是常见漏网之鱼）
• 通过Window > Rendering > Render Pipeline Converter选择 "Built-in Render Pipeline to URP"，依次运行 Rendering Settings、Material Upgrade、Animation Clip Converter、Read-only Material Converter 等转换器
• 材质快照模式：转换前记录_MainTex、_Color等原始值，转换后校验_BaseMap没有丢失——这是防止"材质没变粉色但贴图变白"的关键
• 粒子/雾/烟/特效材质不会被盲目塞进Universal Render Pipeline/Lit，而是优先映射到 URP 粒子 shader

Phase 2：后期处理与相机迁移 🎛️

• 用 Post-processing Stack v2 Converter 把 PPv2 的 Volume、Profile 转成 URP 等价物
• 空 Profile = 没迁移：保存的VolumeProfile若只有空的components，技能会判定 PPv2 迁移失败，而不是被日志糊弄
• 验证期间先禁用旧 PPv2 组件（不删除），避免双重后期导致画面过曝
• 无直接等价物的效果（如 Screen Space Reflections）会被明确列为Manual follow-up，而不是假装迁完了

Phase 3：光照、Lightmaps 与反射探针 💡

• 旧 Lighting Data、lightmap、反射探针先作为参考数据保留
• 场景过曝时先排查"双重后期"，再检查 URP Volume 的曝光/色调映射
• 画面依赖烘焙光照时，在 URP 下重烘焙并刷新反射探针
• 新建的 URP Lighting Settings 必须验证场景确实引用了它——资产文件存在于磁盘上并不算生效

Phase 4：最终验证与报告 ✅

• 保存 → 重载 → 重新查询项目状态，不信工具日志
• 截图代表场景（不是默认测试场景），检查 Console 有无渲染管线错误
• 最终措辞与门禁结果严格一致：任何一项为 Partial/Manual，整体就只能报"部分迁移"，绝不粉饰成"fully migrated"

迁移后画面不对劲？常见问题速查 🩺

技能内置的故障决策树（见 SKILL.md 第 11 节），按症状对号入座：

关键文件导航 📁

想深入阅读技能内部逻辑，以下是核心资料（均为仓库内相对路径）：

• 技能主文件（五阶段流程 + 安全门禁 + 成功门禁）：skills/migrate-birp-to-urp/SKILL.md
• 官方迁移流程与阶段模型：skills/migrate-birp-to-urp/references/migration-workflow.md
• 材质快照、VolumeProfile 持久化等实现模式：skills/migrate-birp-to-urp/references/implementation-patterns.md
• Built-in 质量设置 → URP 位置映射表：skills/migrate-birp-to-urp/references/quality-settings-map.md
• 自定义 shader 分诊：skills/migrate-birp-to-urp/references/custom-shader-triage.md
• Surface Shader / GrabPass 等复杂场景：skills/migrate-birp-to-urp/references/complex-shader-situations.md
• 项目安装与整体用法：README.md

小结 🏁

把 Built-in 项目迁移到 URP 不是一次性操作，而是一场分阶段、可回滚、可验证的持久战。migrate-birp-to-urp 技能的价值在于把老鸟的经验固化为流程：先确认回滚点，五阶段逐步推进，每一步用"保存后的真实状态"而非日志来验收。新手照着它走，也能少踩一半的坑。