migrate-birp-to-urp

对请求进行分类，检查当前项目状态，选择正确的迁移路径，并仔细验证 Built-in 到 URP 的迁移结果。

强制执行参考

对于任何实际的迁移或修复流程，在首次调用会修改项目设置、材质、后处理、光照、探针或场景的 eval 之前，请先阅读 references/implementation-patterns.md。即使是“将此项目迁移到 URP”这样的简短请求，只要已确认回滚安全，也必须遵守此要求。

如果无法加载该资源，请使用此 SKILL.md 中嵌入的规则，并降低置信度：不得仅凭意图或工具日志声称已完成 PPv2 转换、光照／探针刷新或迁移。

关键默认原则

对于“将这个 Built-in 项目迁移到 URP”或“将这个项目转到 URP”之类的简单请求，应启动或继续安全迁移工作流，而不是直接进行转换。

通用升级请求不应要求用户逐一提及所有迁移风险。请检查并处理常见的 Built-in 依赖项，例如 PPv2、烘焙光照／光照贴图、反射探针、粒子／雾／烟雾材质、Quality 级别、摄像机后处理，以及代表性场景验证。

默认按阶段处理：

1. 检测项目属于 Built-in、部分迁移、已使用 URP 还是 HDRP。
2. 将请求归类为标准 3D URP、URP 2D、所选材质转换、仅制定计划或故障排查。
3. 在建议更改之前检查迁移风险：不透明材质、粒子／VFX 材质、自定义着色器、后处理、摄像机效果、烘焙光照／光照贴图／反射探针、Quality 级别以及代表性场景。
4. 在用户确认存在回滚点（例如分支、备份、归档或可丢弃副本）之前，停止所有会修改渲染管线的操作。会修改渲染管线的操作包括安装 URP、在 Graphics／Quality 设置中指定 URP 资源、运行转换器，以及编辑材质或场景。
5. 选择下一迁移阶段，执行该阶段，保存并重新查询其输出，然后报告阶段状态。
6. 将自定义着色器、GrabPass、表面着色器、OnRenderImage、替换着色器和程序包自带的着色器视为后续专项工作，不要将其纳入自动转换器处理。
7. 在宣布迁移全部成功之前，验证代表性场景、Console 输出、摄像机渲染、光照／烘焙 GI 状态、材质、后处理持久性以及质量级别分配。

默认阶段：

• 阶段 0：检查并制定计划。检测渲染管线状态、代表性场景、回滚安全性、PPv2、材质／着色器风险、Quality 级别、光照／光照贴图／探针状态以及自定义渲染代码。
• 阶段 1：URP 设置与受支持的材质转换。安装／复用 URP，在 Graphics／Quality 中创建／分配 URP 资源，转换受支持的不透明材质和粒子／效果材质，并确认没有受支持的材质仍在使用 Built-in 着色器。
• 阶段 2：后处理与摄像机迁移。创建持久化的 URP Volume 配置文件，连接场景中的 Volume 与摄像机后处理，关闭旧版 PPv2 以便验证 URP，并对 SSR 等不受支持的 PPv2 效果进行分类。
• 阶段 3：光照、光照贴图和反射探针。处理过时的 Built-in 光照状态，配置 URP 光照／探针设置，在可行时重新烘焙／刷新，或明确标记光照／探针尚未完全迁移。
• 阶段 4：最终验证与报告。保存、重新加载并重新查询项目状态，捕获代表性场景，检查 Console，并报告已完成、未完成和需手动处理的项目。

如果项目较小且 Unity 保持稳定，一轮中可以完成多个阶段，但不要强行在一次回复中完成所有阶段。宁可如实说明阶段性进展，也不要夸大地声称“全部完成”。

只有在项目状态或用户意图存在尚未解决的实际决策时，才询问配置问题。如果用户说“不要修改文件”，则保持在审计／规划模式，不执行转换或资源编辑。

通用升级约定

当用户提出通用迁移请求并允许进行更改时，根据项目状态推进下一阶段：

1. 检查前，不要要求用户列出已知的内置功能。应自行发现。
2. 如果存在 PPv2、烘焙光照、反射探针、粒子／雾／烟雾材质或多个 Quality 级别，应自动将它们纳入迁移。
3. 优先完成各个阶段，而非一次性完成所有工作。每个阶段都应保存并重新查询自身的输出，并以 Phase complete、Phase partial 或 Blocked 结束。
4. 如果 Unity 编译、软件包安装、域重新加载或耗时较长的光照烘焙中断了流程，应将中断报告为阶段边界，并在下一轮从已保存的部分状态继续，而不是从头开始。
5. 不要依赖用户编写详细的检查清单提示来获得正确行为。详细检查清单用于基准测试或压力测试；普通用户提示仍应触发此分阶段约定。
6. 通用迁移请求允许检查和规划，但并不代表已确认回滚安全性。如果尚未确认回滚点，应在安装软件包或分配 URP 之前停下并请求确认。不要为了先询问备份问题而让项目处于部分洋红色状态。
7. 如果已确认回滚安全，或用户表示项目是可丢弃的副本，则继续当前阶段，不必再次询问日常操作。
8. 在阶段结束时，简要提示下一阶段的操作，或说明接下来应运行哪个阶段。只有当下一阶段会引入新的高成本或高风险操作时，才应先征求确认，例如耗时较长的光照烘焙、删除／清理旧资源或重写自定义着色器。
9. 如果已确认回滚安全，且当前阶段中的常规工作尚未完成，不要询问“是否要继续？”。应继续修复该阶段，直到通过阶段门槛、工具／域重新加载边界中断执行，或出现真正需要决策的新风险。

通用迁移成功门槛

在宣称通用迁移“成功”“已完成”或“已全部迁移”之前，应验证已保存的项目状态，而不只是查看工具日志：

1. Graphics 设置和所有相关的 Quality 级别都指向预期的 URP 资源。
2. URP 资源在已保存状态下具有有效的默认渲染器，且当前 Console 输出中不包含未解决的渲染管线错误，例如 "Default Renderer is missing"。如果分配后出现渲染器错误，请重新查询已保存的渲染器列表和默认索引；在可能的情况下清除过时的 Console 输出，触发新的场景/摄像机验证，并继续修复，而不是在“URP 设置完成”时停止。
3. 受支持的 Built-in 材质（包括粒子/雾/烟雾材质）使用兼容 URP 的着色器，或被明确列为尚未解决的自定义/程序包着色器情况。带纹理/颜色的源材质必须保留其源贴图/颜色；如果源 _MainTex 或 _Color 有内容，那么分配 URP 着色器后缺少 _BaseMap 或 _BaseColor 全白都意味着迁移尚未完成。粒子、雾、烟雾、蒸汽、贴花、VFX、加法和透明效果材质不应一律强制使用 Universal Render Pipeline/Lit；适用时优先选择 URP 粒子/效果着色器，例如 Universal Render Pipeline/Particles/Unlit。
4. 如果源场景使用 PPv2，则必须存在已保存的 URP VolumeProfile，其中包含持久化的非空覆盖组件；代表性场景必须通过 URP Volume 引用该配置文件，并且必须禁用旧版 PPv2，以进行 URP 视觉验证。若已保存的配置文件中 components: []、组件引用为 {fileID: 0}，或场景仍然只引用旧的 PostProcessProfile，则迁移尚未完成。
5. 如果代表性场景使用烘焙/混合光照、Enlighten/实时 GI Lighting Settings 资源、Lighting Data 资源、光照贴图、光照探针或反射探针，则在通用的完整迁移过程中，不要将常规光照/探针修复留作手动后续工作。尝试分配兼容 URP 的 Lighting Settings；在需要时清除/重新烘焙或恢复烘焙；在可行时刷新反射探针；然后保存/重新加载，并验证场景引用的是预期的光照状态。仅创建 .lighting 资源并调用 Lightmapping.lightingSettings = target 和 AssetDatabase.SaveAssets() 并不足够；请标记/保存场景，重新加载/查询，并比较已保存场景的 m_LightingSettings 引用或资源 GUID。如果长时间烘焙或工具中断导致无法完成这些操作，则将迁移标记为部分完成，并从该阶段继续。
6. 必须在迁移验证前有意打开或选择一个代表性场景；不要根据默认/测试场景推断不存在烘焙光照或 PPv2。保存/重新加载后，必须捕获或检查该场景，并检查 Console 输出中是否存在渲染管线、着色器或渲染器功能错误。
7. 最终措辞必须与检查结果一致。只有所有检查均通过时才使用“完成”。如果 URP 已设置，但 PPv2 Volume 持久化、禁用旧版 PPv2、光照烘焙/探针刷新或已保存状态验证仍未完成，则使用“部分完成”。如果任何必需检查仅部分通过，最终回复不得以“已成功迁移”开头。

完整报告检查清单：

• 如果旧 PPv2 配置文件包含已启用的 DepthOfField，新的 URP 配置文件必须包含已保存的 DepthOfField 覆盖项，否则最终报告必须注明该项已省略／需手动处理。
• 如果旧 PPv2 配置文件包含已启用的 AmbientOcclusion，则在可行时配置 URP SSAO Renderer Feature，否则将 AO 标记为需手动处理／部分完成。
• 如果旧 PPv2 配置文件包含已启用的 ScreenSpaceReflections，除非确实添加并验证了 URP Renderer Feature／自定义替代方案，否则将 SSR 列为不受支持／需手动处理。
• 如果场景仍序列化旧的 Lighting Settings GUID，或旧的 m_LightingDataAsset 不为零，则光照迁移为部分完成。
• 如果场景中有反射探针，且 URP 资源仍序列化 m_ReflectionProbeBlending: 0 或 m_ReflectionProbeBoxProjection: 0，则反射迁移为部分完成，除非明确禁用并在报告中说明。
• 如果任何检查清单项目为否，则最终回答不得使用“完成”“完全迁移”或“在 URP 上完全可用”等表述。

不受支持的功能可以保留为需手动处理，但必须准确说明。示例包括需要 URP Renderer Feature／自定义／第三方替代方案的 PPv2 Screen Space Reflections、复杂的自定义着色器移植、GrabPass、替换着色器或由软件包自有的渲染代码。如果任何成功门槛未通过，在允许的情况下继续修复；否则报告迁移部分完成，并列出未完成项；不得将项目描述为已完全迁移。

回归防护摘要：

• 对于实际迁移或修复工作，使用详细的执行回归检查清单。
• 在声明状态前，验证已保存的场景引用：URP Volume／配置文件、Quality 分配、Lighting Settings／Data、URP 资源／Renderer，以及反射探针设置。
• 在更改着色器后，从转换前的快照保留材质源数据，然后恢复 _BaseMap、_BaseColor、纹理缩放／偏移和相关贴图。
• 在最终措辞前，验证具有代表性的视觉效果，包括 PPv2、植被、粒子／特效、烘焙光照、探针和曝光。
• 准确报告各阶段的状态。通过的阶段可以标记为 Phase complete；只有在所有成功门槛均通过时，项目级状态才可以标记为 complete。

执行路径：在编辑器中运行 C#

本技能中的每个 C# 步骤都通过 Unity CLI 在运行中的编辑器内执行。unity-cli 技能负责带你完成这些步骤——安装 CLI、确认有已连接的编辑器、添加项目的 com.unity.pipeline 包、区分编辑器确实不存在还是卡在安全模式，以及发现编辑器的命令目录。请先遵循该技能；不要在这里重新推导这些内容。

有两件事需要你自行确认：

• **你特别需要 eval，而不仅仅是能连接到编辑器。**请确认它出现在目录中。 它是否存在取决于 Pipeline 包的版本，而不是 CLI，因此即使安装正常，也可能缺少它——如果缺少，请说明并停止。

• 如果编辑器版本低于 6000.3，预计 Pipeline 包将完全无法工作；请正确判断症状，而不是反复重试。com.unity.pipeline 使用了 IPreprocessBuildWithContext 和 BuildCallbackContext，这两者由 Unity 在 6000.3 中引入；但该包自己的清单声明了 "unity": "6000.0"，因此它能顺利安装，随后却会编译失败。实测结果：这两个类型存在于 6000.3 / 6000.4 / 6000.5 中，在 6000.0 / 6000.1 / 6000.2 以及 2022 和 2023 系列中不存在。症状具有误导性——服务始终不会启动，unity status 不会显示任何条目，也不会报错；真正原因是编辑器日志中这两个类型触发了 CS0246。如果遇到这种情况，请告诉用户编辑器版本太旧，无法使用 Pipeline 包，而不要去调试 CLI。

  **这在此处比大多数技能都更重要：**迁移项目、脱离内置渲染管线的人，往往使用的是较旧版本的编辑器。

• **无法在没有编辑器的情况下安全地编写渲染管线迁移操作。**分配 URP 资源、转换材质和重新烘焙光照都需要运行中的编辑器。无法连接到编辑器就应停止，而不是手动编辑 ProjectSettings/GraphicsSettings.asset。

使用 unity command eval --code '<snippet>' 运行 C#。unity command 默认超时时间为 30 秒，这一点很重要：安装 URP 会触发包刷新和域重载，耗时会超过此限制。应将其视为阶段边界，而不是延长超时时间。

将 C# 传递给 eval

eval 编译的是语句块，而不是文件。因此有三点需要注意；违反任何一点都会导致编译错误，而不是警告：

• **不能使用 using 指令。**编译器会将 using UnityEngine; 视为资源释放语句并拒绝编译（CS0210）。
• **类型必须使用完整限定名。**裸写 GraphicsSettings 或 Volume 无法解析（CS0246 / CS0103），而裸写 Object 会与 object 产生歧义（CS0104）。
• 扩展方法不可用，因为它们通过 using 解析。本技能原本可能会用到的两个扩展方法：camera.GetUniversalAdditionalCameraData() 应改为 camera.GetComponent<UnityEngine.Rendering.Universal.UniversalAdditionalCameraData>()；LINQ 调用必须改为静态写法——使用 System.Linq.Enumerable.FirstOrDefault(sequence, predicate)， 而不是 sequence.FirstOrDefault(predicate)。

两种执行模式——根据代码片段的形式选择

参考资料中包含这两种形式，二者不可互换：

• 语句形式（一组独立语句，例如上面的检测代码片段）——直接传给 eval，使用完全限定名称，不要添加 using 行。
• 类或方法形式（任何声明了 class、static 方法或 [MenuItem] 的内容，例如材质快照模式）——这些是项目文件，而非 eval 输入。类声明不能展平成语句块。将代码片段保存到 Assets/Editor/，让 Unity 编译，然后通过一行 eval 调用其入口点。保留该文件中的 using 指令；它们在那里是正确的。

对于多步骤迁移，脚本方式无论如何都更加可靠：它能经受 URP 安装和材质转换触发的域重载，而较长的 eval 负载则不行。

检测活动渲染管线

var rp = UnityEngine.Rendering.GraphicsSettings.defaultRenderPipeline;
var qrp = UnityEngine.QualitySettings.renderPipeline;
return $"graphics={(rp == null ? "NULL (Built-in)" : rp.GetType().Name + ":" + rp.name)}, "
     + $"activeQualityLevel={(qrp == null ? "inherits Graphics" : qrp.GetType().Name + ":" + qrp.name)}";

UniversalRenderPipelineAsset 表示 URP；HDRenderPipelineAsset 表示 HDRP；两者均为 NULL 则表示 Built-in。还要检查每个质量等级的赋值情况——项目可能已在 Graphics 设置中切换管线，但某个 Quality 等级仍指向其他资源或未指向任何资源：

var names = UnityEngine.QualitySettings.names;
var rows = new System.Collections.Generic.List<string>();
for (int i = 0; i < names.Length; i++)
{
    var a = UnityEngine.QualitySettings.GetRenderPipelineAssetAt(i);
    rows.Add($"{i}:{names[i]}={(a == null ? "inherits Graphics" : a.name)}");
}
return string.Join(", ", rows);

如果项目所用的 Unity 版本中没有 GetRenderPipelineAssetAt，请改为读取 ProjectSettings/QualitySettings.asset，而不要在运行时切换等级——SetQualityLevel 会修改项目状态。

0. 准备工作：管线检测和参考资料加载

在进行任何其他操作之前，必须确定活动渲染管线和迁移模式：

1. 检测管线： 运行上文执行路径部分中的渲染管线检测代码片段。
   • 如果 currentRenderPipeline 或 defaultRenderPipelineAsset 引用的是 UniversalRenderPipelineAsset -> URP。
   • 如果未分配渲染管线资源 -> Built-in。
   • 如果引用的是 HDRenderPipelineAsset -> HDRP。说明此技能仅涵盖从 Built-in 迁移到 URP。可以提供基本的对比建议，但不要使用此技能执行 HDRP 迁移。
2. 加载基础参考资料： 阅读 references/migration-workflow.md。
3. 在相关时加载着色器参考资料： 如果请求提及材质、着色器、洋红色材质、渲染错误、图像效果或自定义渲染，还要阅读：
   • references/custom-shader-triage.md
   • 如果检查或项目文件搜索发现高级着色器／效果模式，则阅读 references/complex-shader-situations.md
4. 在相关时加载质量设置参考资料： 如果请求提及阴影、光照、烘焙光照、光照贴图、反射探针、质量设置、视觉差异或迁移后的性能，还要阅读 references/quality-settings-map.md。
5. 执行时加载实现模式： 如果请求允许实际迁移更改、后处理转换、烘焙光照／探针修复，或从部分迁移状态恢复，还要阅读 references/implementation-patterns.md。
6. 将请求归类为以下其中一项：
   • 整个项目从 Built-in 迁移到 URP
   • Built-in 2D 迁移到 URP 2D
   • 仅转换选定材质
   • 仅规划／说明
   • 排查先前迁移后出现的问题
7. 如果项目已使用 URP， 切换到故障排查模式，而不是盲目重新运行设置。
8. **只有在明确管线和迁移路径后，**才能继续。

1. 评估当前迁移状态

进行任何更改前，检查现有内容：

1. 检查管线状态和分配位置：
   • 运行上方执行路径部分中的两个渲染管线检测代码片段——Graphics 设置中的一个，以及逐质量级别的一个。
   • 如果项目有质量级别，请检查每个级别使用的 Render Pipeline Asset，再判断项目是否已完全切换。
2. 盘点迁移涉及的内容： 使用 eval 和 UnityEditor.AssetDatabase.FindAssets 或等效的资源查询，盘点：
   • 材质，包括通常使用内置粒子着色器的粒子/VFX 材质
   • 植被材质，包括草地、树木、地形细节、SpeedTree、广告牌、叶片卡片、镂空和风驱动植被材质
   • 着色器
   • 场景和重要预制件
   • URP 资源和 Renderer 资源（如有）
   • 后期处理配置文件/Volume 配置文件
   • Lighting Settings 资源、Lighting Data 资源、光照贴图、光照探针、反射探针，以及混合/烘焙光源
3. 扫描渲染风险标记： 使用项目文件搜索、AssetDatabase.FindAssets 或简短的 eval 文件扫描，搜索项目中的渲染相关模式，例如：
   • PostProcessLayer、PostProcessVolume、UnityEngine.Rendering.PostProcessing
   • OnRenderImage(、RenderWithShader、SetReplacementShader
   • #pragma surface、GrabPass、CGPROGRAM
   • CommandBuffer、自定义着色器包含路径或包着色器命名空间
   • 植被标记，例如 Nature/、SpeedTree、TreeCreator、Grass、Foliage、_Cutoff、_AlphaClip、_Cull、billboard 或风相关关键字
4. 如果已安装 PPv2，但 grep 没有找到任何内容， 请通过组件/类型使用 Unity API 检查已打开的场景和配置文件资源。场景 YAML 和序列化的包引用可能无法通过文本搜索找到。
5. 确定项目类型： 判断项目主要是 3D、主要是 2D，还是混合类型。
6. 报告发现： 在提出转换方案前，先总结当前状态。例如：
   • “项目仍在使用 Built-in，没有分配 URP 资源，包含 PPv2 引用，并且有多个使用表面着色器语法的自定义着色器。”

2. 收集需求

确定用户的实际需求。如果请求含糊，请提问。

常见请求的默认解释如下：

用户说	默认解释
“将此项目升级到 URP”	全项目迁移
“将这个 2D 项目迁移到 URP”	从 Built-in 2D 迁移到 URP 2D
“转换这些材质”	针对性材质转换
“我的材质变成粉色了”	迁移后的着色器/材质故障排查
“迁移到 URP 后光照效果不对”	质量和视觉一致性故障排查
“暂时不要做任何更改”	仅规划/审计

需要收集的信息

• 范围： 全项目、选定材质，还是仅故障排查
• 目标渲染器： 标准 URP 或 URP 2D
• 验证目标： 用户最关注哪些场景、预制件或摄像机
• 风险容忍度： 是否可以接受有限的手动后续处理
• 渲染依赖项： 自定义着色器、Asset Store 着色器、PPv2、烘焙光照/光照贴图/探针、图像效果、命令缓冲区、替换着色器或多个质量级别
• 执行权限： 仅规划还是实际更改项目

3. 安全门

执行任何会更改项目流水线的步骤之前：

1. 确认回滚安全性。
   • 在用户确认已有备份、分支、存档、可丢弃副本或回滚点之前，绝不安装 URP、分配 URP 资源、运行 Render Pipeline Converter、编辑材质或更改迁移场景状态。
   • 如果不具备回滚安全性，不要只将项目部分切换到 URP。停止规划，并先请求用户确认回滚安全性。
2. 将引擎升级风险与流水线升级风险分开处理。
   • 如果项目还要升级到新的 Unity 版本，建议先升级引擎，再迁移流水线。不要将两者视为一次盲目操作。
3. **如果已确认回滚安全性，**则视为该确认涵盖整个迁移过程。在每个转换器运行前都不要再次询问；应继续完成设置、材质转换、PPv2 迁移、光照/探针处理、保存/重新加载验证和最终报告，除非出现新的高风险决策。
4. **如果用户已经授权进行完整的可丢弃迁移，**则不要在常规设置或可恢复错误之后请求继续操作的许可。继续处理下一个未完成的迁移阶段。只有在出现新的破坏性清理决策、软件包/域重新加载导致执行停止，或重复修复尝试达到验证迭代上限时，才询问用户。
5. **如果项目已经部分迁移，**请确认之前是否已确认回滚安全性。如果已确认，从第一个未完成的项目继续。如果未确认，报告部分迁移状态，并在进行更多更改之前先询问用户。

4. 选择迁移路径

根据项目选择正确的路径：

路径 A：标准 3D Built-in 转 URP

• 用于常规 3D Built-in 项目迁移到标准 URP。

路径 B：Built-in 2D 转 URP 2D

• 用于主要为 2D 的项目，且用户需要 URP 2D 光照或渲染器行为。
• 不要将其视为与标准 URP 相同的工作流。

路径 C：仅转换指定材质

• 仅当项目已经使用 URP，且用户希望转换选定材质时使用。

路径 D：排查现有迁移问题

• 当项目已经使用 URP 或已尝试过迁移时使用。
• 优先修复影响最大的故障，不要盲目重新运行整个迁移流程。

5. URP 设置工作流

严格按以下顺序设置：

1. 确保已安装 URP。
   • 安装 URP 可能会触发软件包刷新、编译和域重新加载。请将其视为阶段边界。
   • 不要在 eval 调用中对 UnityEditor.PackageManager.Client.Add 无限期地等待。发起安装请求后，等 Unity 完成刷新，再通过 Packages/manifest.json、软件包列表或 URP 类型/资源是否存在来进行验证。
   • 如果软件包安装导致 eval 调用超时或没有返回结果，请等 Unity 完成编译后，在新的轮次中继续。不要重新开始整个迁移，也不要重新安装 URP；检查部分完成的状态并从那里继续。
2. 如果所需的 URP 资源和渲染器资源尚不存在，则创建它们。
3. 在 Graphics 设置和所有相关的 Quality 级别中分配 URP 资源。
4. **对于 2D 项目，**请在转换之前创建并分配正确的 2D Renderer 资源。
5. **如果 URP 资源已存在，**应检查并在适用时复用它，而不是自动创建重复资源。
6. 在目标配置中 URP 确实成为活动渲染流水线之前，不要继续。

6. 转换工作流

实际转换工作请遵循 references/migration-workflow.md。

1. 选择正确的 Render Pipeline Converter 路径：
   • Built-in Render Pipeline to URP
   • Built-in Render Pipeline 2D to URP 2D
2. 初始化转换器并检查候选更改，然后再进行转换。
3. **对于标准的 Built-in 到 URP 迁移，**优先使用参考文档中介绍的适用转换器：
   • Rendering Settings
   • Material Upgrade
   • Animation Clip Converter
   • Read-only Material Converter
   • Post-processing Stack v2 Converter
4. **对于选定材质的转换，**使用针对材质的转换工作流，而不是转换整个项目。
5. 转换前检查警告和失败项。
6. 仅在用户确认项目可以安全更改后运行转换。
7. 确认每个材质实际使用的着色器——不要假设转换器选择了 3D 目标。MaterialUpgrader.FetchAllUpgradersForPipeline 会同时返回 2D 和 3D 提供程序集合，而两者都以相同优先级声明支持 Standard，因此在 3D 项目中，普通的 Standard 材质可能会悄无声息地转换为 Universal Render Pipeline/2D/Mesh2D-Lit-Default，而不是 Universal Render Pipeline/Lit。整个过程不会报错，材质也不会变成洋红色，因此只有读取着色器名称才能发现这一问题——在 6000.5.8f1 上测得。 随后读取每个已转换资源的 shader.name，确认其与映射表中的预期目标一致。如果某个资源在 3D 项目中使用了 2D/ 着色器，请从回滚点还原这些资源，并使用经过 3D 筛选的升级器列表进行转换，或按照 references/implementation-patterns.md 中的手动模式转换。
8. 转换后，验证已保存的项目状态。
   • 重新打开或重新查询有代表性的资源，不要只相信命令输出。
   • 在场景级编辑后，保存资源和已打开的场景。仅调用 AssetDatabase.SaveAssets() 无法证明场景组件、相机数据、当前照明设置、反射探针和 PPv2 启用状态已保存。
   • 确认 URP 资源已分配到 Graphics 设置和预期的 Quality 级别。
   • 对于 Quality 级别，请通过重新查询 QualitySettings.GetRenderPipelineAssetAt(i)，或读取 ProjectSettings/QualitySettings.asset 中已保存的 customRenderPipeline 条目进行验证。如果这些条目仍为 {fileID: 0}，则表示 Quality 级别尚未显式分配资源。
   • 不要调用猜测的质量设置 API，例如 QualitySettings.SetRenderPipelineAssetAt；在不提供该 API 的 Unity 版本中，切换到每个目标级别并调用 QualitySettings.SetQualityLevel(index)，设置 QualitySettings.renderPipeline = urpAsset，然后恢复原级别，并验证已保存的 customRenderPipeline 值。
   • 确认已转换的材质确实引用了 URP 着色器。
   • 确认原本带有源反照率贴图的代表性材质现在具有非空的 _BaseMap 值。此项检查必须与转换前的材质快照进行比较；不要将转换后的 _MainTex 作为判断依据。
   • 确认粒子/VFX 材质不再引用内置粒子着色器 ID 或旧着色器名称；在适用情况下，使用 Universal Render Pipeline/Particles/Unlit 等 URP 粒子着色器。如果材质名称或路径包含 Particle、Fog、Smoke、Steam、VFX、Additive 等效果相关词语，应保留透明/加色效果，而不是默认使用 URP Lit。
   • 确认植被材质保留了剪裁/Alpha 裁剪、渲染面意图、纹理、色调、法线以及预期的风动/公告板效果。如果草地/树木卡片因专用着色器行为丢失而变得不透明或静止，则材质转换尚未完成。
   • 如果尝试了 PPv2 转换，请确认已保存的 URP Volume 配置文件包含持久化的非空 components 条目，并且场景/相机连接使用与 URP 兼容的组件。
   • 如果存在烘焙光照，请保留旧的 Lighting Data 和光照贴图作为参考数据，然后验证它们在 URP 中是否仍能产生可接受的视觉效果。如果新建了 Lighting Settings 资源，请确认场景在保存/重新加载后确实引用了该资源；资源存在于磁盘上并不足以证明这一点。在实际的通用迁移中，如果过时的烘焙数据或反射探针影响了视觉一致性，请尝试重新烘焙/刷新；如果本轮无法完成，请报告迁移尚未完成，并在之后从光照/探针阶段继续。
   • 不要仅凭意图声称“已刷新反射探针”。请验证新的或已更新的探针输出、已更改并保存的反射探针资源，或探针渲染工具的成功输出。如果现有 EXR 文件未发生变化，请说明这些探针已作为参考保留，或仍需刷新。
   • 如果任何验证失败，请将相应项目报告为未完成/需要手动跟进，而不是声称已完成迁移。

7. 着色器与材质排查

当材质呈洋红色、着色器编译失败或视觉效果严重偏离时，请先查阅 references/custom-shader-triage.md。

1. 确认受影响的材质和着色器。
   • 检查材质实际指定的着色器，而不只是场景表现出的症状。
2. 编辑着色器代码前，先查看 Console 和 Inspector 中的错误。
3. 判断着色器的情况：
   • 转换器应能处理的受支持 Built-in 着色器
   • 可能可以安全移植的简单自定义着色器
   • 需要制定范围明确的迁移计划的复杂自定义着色器
   • 需要实现镂空、双面叶片、公告板、地形细节渲染或风效的树叶/植被着色器
   • 由软件包或 Asset Store 提供的着色器，可能需要查阅维护者文档、进行范围明确的自定义移植，或手动跟进
4. **遇到复杂着色器情况时，**请查阅 references/complex-shader-situations.md。
5. 优先采用最小且安全的修复方案。
   • 先恢复代表性材质的渲染。
   • 验证结果后，再将修复扩展到更多资源。
6. 除非映射关系明确、经过测试且范围明确，否则绝不要在整个项目中批量搜索并替换着色器代码。

8. 后期处理、摄像机与渲染效果排查

Built-in 项目通常依赖的不止材质转换。

1. **如果存在 PPv2，**请检查转换器的输出，并验证生成的 URP Volume、配置文件和摄像机行为。
   • 转换前，清点现有的 PostProcessVolume、PostProcessLayer 和 PPv2 PostProcessProfile 资源。
   • 如果有 URP Post-processing Stack v2 Converter，优先使用它，而不是凭记忆手动创建等效配置文件。
   • 转换后，确认已保存的 URP VolumeProfile 资源包含持久化的覆盖组件，而不是 components: [] 这样的空配置文件，或引用已失效的 {fileID: 0} 组件。
   • 如果通过脚本创建配置文件，VolumeProfile.Add<T>() 只会创建组件对象；对于持久化的配置文件资源，还要调用 AssetDatabase.AddObjectToAsset(component, profile)，将配置文件和组件标记为已修改，保存资源，重新加载资源，并在报告成功前统计已保存的非空组件数量。如果已保存的配置文件包含 {fileID: 0} 组件条目，请重新创建或修复配置文件后再宣称迁移成功。
   • 验证有代表性的场景包含预期的 Volume 对象，并且在需要时，目标摄像机具有启用后处理的 UniversalAdditionalCameraData。
   • 如果源场景仍然只序列化了 PPv2 sharedProfile 引用，而没有任何 URP Volume 引用新的 VolumeProfile，则 PPv2 迁移尚未完成，即使磁盘上存在 URP 配置文件资源也是如此。
   • 如果活动的 URP Volume 引用了空配置文件，应将其视为场景连接未完成，而不是有效的后处理。请修复配置文件，或说明 PPv2 迁移不完整。
   • 检查是否仍保留旧的 PostProcessVolume / PostProcessLayer 组件。如果仍然保留，请说明这是有意保留、无害的旧组件，还是尚未解决的迁移工作。
   • 如果仅将旧 PPv2 组件作为参考保留，同时有活动的 URP Volume，请禁用旧 PPv2 组件/层，以便验证 URP 的视觉效果，避免重复后处理。在效果一致性得到认可或用户批准清理之前，不要删除它。
   • 在确认存在经过验证的 URP 替代方案，或用户接受丢弃这些效果/后续手动处理之前，不要将移除 PPv2 包、组件或配置文件作为清理步骤。
   • 实际迁移时，如果可以获取源配置文件，不要将常见的 PPv2 效果一致性验证含糊地留作手动任务。请为 Bloom、Color Adjustments/Tonemapping、Vignette 和 Depth of Field 等常见可映射效果创建持久化的 URP 覆盖，并验证已保存的配置文件包含非空组件。
   • 对于不受支持或无法等效实现的效果，可以列为后续手动处理，例如 PPv2 Screen Space Reflections 或应改用 Renderer Feature / SSAO 设置、而非直接 Volume 覆盖的 Ambient Occlusion。
   • 如果无法可靠地创建 URP Volume 覆盖，请记录 PPv2 效果及其 URP 等效方案，而不要声称这些效果已迁移。
2. 不要将工具的临时成功视为后处理迁移成功。
   • 命令日志显示“Added Bloom”还不够。保存并重新加载后，重新读取已保存的 VolumeProfile 资源或检查场景。
   • 如果已保存的配置文件为空，请说明 PPv2 设置仅已记录或部分准备，尚未迁移。
3. **如果 grep 找到 OnRenderImage，**请将其视为自定义全屏效果。
   • 在 URP 中，自定义全屏效果应迁移到 ScriptableRenderPass、Renderer Feature 或 URP 自定义后处理，而不是继续使用 Built-in 图像效果路径。
4. **如果 grep 找到 RenderWithShader 或 SetReplacementShader，**请将其视为替换着色器案例。
   • 这类效果通常需要专门设计 URP Renderer Feature 或自定义 Pass 方案。
5. **如果某个效果依赖场景颜色、深度或法线，**请验证适用于 URP 的实现路径，不要假定 Built-in 中的方法仍然适用。
6. **如果自定义摄像机在 Built-in 中叠加了效果，**迁移后请明确验证摄像机输出，不要假定效果一致。
7. 对于高级着色器/效果排查问题，请提供具体的替代实现模式。
   • 对于 GrabPass，请说明 _CameraOpaqueTexture / Scene Color、所需的 URP 资源设置，以及透明物体排序可能与 Built-in 不同这一限制。
   • 对于 OnRenderImage，请说明 ScriptableRendererFeature 和 ScriptableRenderPass。展示 Unity 6 风格模板时，请使用带临时 RTHandle 和 Blitter.BlitCameraTexture 的参考模式。
   • 切勿建议将 Blitter.BlitCameraTexture(cmd, source, source, material, pass) 或其他源到源 Blit 作为 OnRenderImage 的主要替代方案。如果不打算展示更安全的临时目标模式，请省略代码示例，改为解释架构。
   • 对于 Surface Shaders，请说明 #pragma surface 在 URP 中没有直接对应实现，并根据效果复杂度选择 Shader Graph 或 URP HLSL 顶点/片元着色器重写方案。
   • 不要只说“重写它”；请提供切实可行的首个移植步骤和验证目标。

9. 质量、光照与视觉一致性审查

当用户提到视觉不匹配、阴影、性能或质量设置时，请使用 references/quality-settings-map.md。

1. 检查 Graphics 设置和每个启用的 Quality 级别。
   • 如果某个 Quality 级别没有自定义 URP 资源，请说明该级别是有意回退到 Graphics 设置，还是仍需显式分配。
   • 除非检查了每个相关级别，否则不要声称所有质量级别都已迁移。
   • 如果使用序列化的项目设置，保存的字段通常是 customRenderPipeline；除非保存的资源证明了分配结果，否则仅写入猜测的字段（例如 renderPipelineAsset）并不足够。
   • 如果通过脚本分配，请采用 URP 的 Render Settings 转换器使用的相同模式：缓存 QualitySettings.GetQualityLevel() 的结果，对每个目标级别调用 QualitySettings.SetQualityLevel(index)，设置 QualitySettings.renderPipeline = urpAsset，然后恢复原质量级别并验证磁盘上的结果。
2. 检查常见的 URP 资源设置，这些设置会影响视觉一致性：
   • 阴影
   • 阴影距离和级联
   • MSAA
   • 渲染比例
   • 当效果依赖相关设置时，检查 HDR、不透明纹理和深度纹理设置
3. 不要承诺光照会自动完全一致。
   • Built-in 和 URP 在光照衰减、烘焙 GI 外观、阴影调校、反射探针响应、色调映射、曝光和后期处理行为方面可能存在差异。
4. **对于使用烘焙光照的场景，**应将现有光照贴图和 Lighting Data 视为参考资料，而非保证最终 URP 输出的依据。
   • 清点 Lightmapping.lightingSettings、场景 LightmapSettings、烘焙/混合光源、光照探针、反射探针以及任何现有的 LightingDataAsset。
   • 在用户有视觉参考或回滚点之前保留烘焙数据；但如果过时的 Built-in 光照贴图导致场景过曝或失真，就不要继续将其作为最终 URP 光照方案启用。
   • 如果场景看起来过曝、过暗或不匹配，请先在 URP 验证期间停用旧版 PPv2，以隔离后期处理/曝光的影响，然后再检查 URP Volume 的曝光、色调映射和泛光，之后才调整灯光。
   • 如果清除烘焙数据后场景不再过曝，请将旧光照贴图/Lighting Data 识别为过时或不兼容的启用数据。然后使用最终的 URP 资源、渲染器、Volume 和 Quality 设置在 URP 下重新烘焙，而不是针对过时烘焙结果调校灯光。
   • 如果创建或分配兼容 URP 的 LightingSettings，请将光照设置和活动场景标记为已修改，保存场景，然后重新加载或重新查询，并验证保存后的场景引用了预期的 .lighting 资源。仅调用 AssetDatabase.SaveAssets() 不会保存场景中的 Lightmapping.lightingSettings 引用。如果保存后的场景仍指向 Enlighten/实时 GI 设置资源，请勿报告“已启用 Baked GI”。
   • 当请求涉及视觉一致性，且 Built-in 烘焙留下了旧的 LightingData.asset / 反射探针 EXR 时，应将其视为参考数据，直到在 URP 下重新烘焙/刷新。不要仅凭旧烘焙数据声称保留了视觉一致性。
   • 如果视觉一致性很重要，建议清除/重新烘焙光照并刷新反射探针。除非已在 URP 设置后对有代表性的场景进行视觉检查，最好还在 URP 下完成烘焙，否则不要声称烘焙光照已成功迁移。
5. **对于 2D 光照项目，**确保精灵和 Tilemap 在需要时使用兼容 URP 的受光材质。
6. **对于性能回退，**请检查问题是否源于：
   • 更繁重的 URP 资源设置
   • 后期处理
   • 额外的阴影开销
   • 自定义着色器移植或未批处理的着色器
7. **更改 URP 资源设置时，**保存后请重新读取已保存的资源或查询相关属性，然后再报告 MSAA、附加光源限制、HDR、深度纹理或不透明纹理等值。

10. 验证

完成设置、转换或故障排查后，请验证结果：

1. **捕获场景：**在具有代表性的场景中捕获 Scene View 或特定摄像机画面 — 请参阅 references/capturing-the-editor.md。
2. 评估结果：
   • 除非仍存在尚未解决的自定义着色器阻碍，否则不应有洋红色材质
   • 主要光照和阴影表现符合预期
   • 烘焙 GI／光照贴图、光照探针和反射探针符合要求，或已明确标记为需要重新烘焙／刷新
   • 摄像机渲染了预期内容
   • 后处理或全屏效果仍能正常工作
   • 适用时，精灵、瓦片地图或 2D 光照正常工作
3. 验证持久化项目数据，而不只是视觉输出。
   • 检查已保存的 URP 资源、渲染器资源、场景引用、材质着色器 GUID／名称、Quality 设置和 Volume 配置文件。
   • 在判定烘焙光照、PPv2 或反射探针不存在之前，确认已打开或以其他方式检查过具有代表性的场景，而不是默认场景／测试场景。
   • 对于材质迁移，验证时也要包含粒子／VFX 材质。仍有内置粒子着色器 ID 或旧版粒子着色器名称，意味着材质迁移尚未完成。
   • 对于 PPv2 迁移，已保存的 URP VolumeProfile 资源必须包含预期的覆盖组件，才能报告迁移已完成。
   • 如果工具日志报告已映射后处理，但重新加载已保存的配置文件后显示 components: []，则应以工具日志为准，报告迁移失败／未完成。
   • 对于烘焙光照场景，请检查 Lighting Settings、Lighting Data／光照贴图引用、光照探针和反射探针。编译成功并不能证明烘焙光照效果一致。如果旧光照贴图导致过曝，请清除当前烘焙数据，并在 URP 下重新烘焙，然后再判断效果是否一致。分配新的光照设置后，请验证已保存的场景引用，而不只是确认新的 .lighting 资源存在。
   • 如果仍分配着旧的 LightingData.asset，且反射探针 EXR 未重新生成或未在目视检查后明确接受，则应将光照／探针归类为已保留或部分完成，而不是已刷新。
4. 使用 Unity.GetConsoleLogs 检查 Console 输出，查找着色器、渲染管线或渲染器功能错误。
5. **先修复影响最大的那个问题，**然后再次验证。
6. 最多重复 3 次，之后报告剩余阻碍，或询问用户希望如何继续。

11. 故障排查决策树

如果用户报告迁移问题，请按以下流程进行诊断：

“迁移”后项目仍表现得像在使用 Built-in

1. 检查 Graphics 设置中是否分配了 URP 资源。
2. 检查相关 Quality 等级是否也指向 URP 资源。
3. 在排查其他问题之前，先确认当前渲染管线确实为 URP。

安装 URP 后迁移停止

1. 将此情况视为软件包刷新／域重载的边界，而不要仅凭这一点认定完整迁移失败。
2. 重新检查 Packages/manifest.json 和软件包状态。如果 URP 已安装，不要重新安装。
3. 检查是否存在部分资源，例如 URP 资源、渲染器资源、已转换的材质、空的 Volume 配置文件，以及场景组件变更。
4. 如果 URP 已安装／分配，但仍以 Built-in 材质为主，或场景显示洋红色，则材质转换是接下来最需要完成的事项。如果已确认回滚安全，不要仅因 URP 设置完成就将其报告为完成并停止。
5. 从首个未完成的验证事项继续：Graphics／Quality 分配、渲染器资源有效性、材质转换、PPv2 到 URP Volume 的迁移、烘焙光照重新烘焙，然后进行最终验证。
6. 如果之前的聊天记录／导出内容没有最终回复，请将其视为不完整的证据，并在新聊天／轮次中继续。

材质呈洋红色／亮粉色

1. 检查 Console 和 Inspector 中是否有着色器错误。
2. 确认材质使用的是受支持的 Built-in 着色器、自定义着色器，还是由程序包提供的着色器。
3. 如果是受支持的 Built-in 着色器，先检查转换器路径或针对性的材质转换。
4. 如果项目已经使用 URP，且仍有许多受支持的 Built-in 材质，应将其视为材质转换不完整，而非最终视觉一致性工作。
5. 如果是自定义着色器或程序包着色器，请参阅 references/custom-shader-triage.md，必要时再参阅 references/complex-shader-situations.md。

场景明显变暗、变亮，或看起来就是“不对”

1. 对比 Scene View 和 Game View 的截图。
2. 首先检查是否重复进行后期处理：保留的 PPv2 PostProcessVolume / PostProcessLayer 与启用的 URP Volume 同时存在，可能导致验证截图过曝或出现其他失真。
3. 检查阴影、环境光／环境照明、色调映射、天空盒、曝光、泛光和后期处理。
4. 检查烘焙照明状态：Lighting Settings、Lighting Data 资源、光照贴图引用、混合／烘焙光源、光照探针和反射探针。
5. 在重写内容之前，先检查质量级别分配和 URP 资源设置。
6. 如果清除烘焙数据后严重过曝问题得到解决，应将旧光照贴图视为过时的活动数据：仅将其保留为参考／回滚依据，然后在 URP 下重新烘焙。
7. 如果场景依赖烘焙照明，请在宣称视觉效果一致之前，建议在 URP 下重新烘焙并刷新反射探针。
8. 请记住，Built-in 和 URP 的光照衰减可能不同；应将其视为调优任务，而非转换失败的证明。

后期处理或全屏特效消失

1. 检查是否已转换 PPv2，以及目标摄像机和体积设置是否仍然有效。
2. 检查已保存的 URP VolumeProfile 资源。空配置文件表示 PPv2 特效实际上并未迁移。
3. 检查场景中是否仍有启用的旧 PostProcessVolume / PostProcessLayer 组件。
4. 搜索 OnRenderImage、自定义 blit 代码或替换着色器摄像机特效。
5. 使用兼容 URP 的方法移植特效，而不是尝试原样保留 Built-in 回调路径。

透明／折射／扭曲特效异常

1. 检查着色器是否依赖 GrabPass 或类似的 Built-in 屏幕复制工作流。
2. 如果是，请参阅 references/complex-shader-situations.md，并选择 Scene Color／Renderer Feature／自定义通道方案。

2D 灯光无法影响精灵

1. 确认项目实际使用的是 2D Renderer。
2. 确认现有精灵材质已在需要时升级为兼容 URP 的 Lit 材质。
3. 不要认为拖入新的精灵就能证明旧项目材质设置正确。

迁移后性能下降

1. 检查渲染比例、阴影、额外灯光、MSAA、后期处理、不透明／深度纹理以及其他 URP 资源设置。
2. 检查自定义着色器移植是否失去了批处理兼容性或引入了额外通道。
3. 在认定唯一解决方案是回滚之前，先调整设置。

自定义着色器可以编译，但视觉效果仍然不对

1. 判断问题是简单的参数偏差，还是结构性不兼容。
2. 如果着色器来自表面着色器、GrabPass、替换着色器工作流或自定义光照路径，应将其视为复杂迁移案例。
3. 在将方案推广到整个项目之前，先验证一种有代表性的材质。

12. 核心防护措施

• 首先检测当前使用的渲染管线；如果是 HDRP，请说明不匹配之处，并且只提供基本的比较指导。
• 在确认具备回滚安全性之前，不要修改项目；应先停留在规划模式，不要安装 URP、分配资源、运行转换器、编辑材质或场景。
• 不要将工具日志或已创建的资源视为证明；应先保存、重新加载并重新查询 Graphics、Quality、材质、Volumes、光照、探针、Console 和代表性场景，然后再报告状态。
• 不要将部分阶段的完成情况说成整个项目已完成；应根据成功门槛报告 Phase complete、Partial migration 和 Manual follow-up。
• 不要批量改写脆弱的渲染代码；应针对自定义着色器、GrabPass、OnRenderImage、替换着色器、包自带的渲染代码和不受支持的 PPv2 效果，使用范围明确的映射。

13. 汇报结果

总结以下内容：

• 使用了哪种迁移路径
• 项目仍在使用 Built-in、已部分迁移，还是已完全迁移到 URP
• 运行了哪些转换器
• 自动修复了哪些内容
• 仍需哪些手动操作
• 验证了哪些场景、材质或摄像机
• 仍存在哪些风险，尤其是复杂着色器、包效果和视觉一致性方面
• 后处理是已完全迁移、已部分准备，还是仅记录了手动跟进事项
• Quality 级别是否已明确分配，或是否有意依赖 Graphics 设置回退
• 粒子/VFX 材质是否已转换，或仍需后续处理 URP 粒子着色器
• 烘焙光照/lightmaps/反射探针是作为参考保留、经视觉验证、重新烘焙/刷新，还是留待手动跟进
• 曝光、色调映射、环境补光以及摄像机/Volume 后处理连接是否已通过视觉检查并调整平衡，或仍未完成

谨慎使用表示完成的措辞。如果报告中包含任何 Partial、Manual follow-up、not validated、may still need 或不受支持的功能，应明确指出哪些已完成阶段通过验证，并将整体迁移状态表述为部分完成/需要手动跟进。不要一边声称整个项目已“完成”，一边列出手动跟进事项。

参考资料

• 迁移工作流
• 自定义着色器分类
• 复杂着色器情况
• Quality 设置映射
• 实现模式

激活此技能时，请主动阅读 references/migration-workflow.md。如果请求涉及材质、着色器、洋红色材质、自定义渲染或全屏效果，也请阅读 references/custom-shader-triage.md 和 references/complex-shader-situations.md。如果请求涉及迁移后的视觉差异、光照、烘焙光照、lightmaps、反射探针、阴影或性能，也请阅读 references/quality-settings-map.md。如果用户允许实际修改以进行迁移，或要求继续/修复部分迁移，也请阅读 references/implementation-patterns.md。