Unity URP Shader迁移实战：从内置管线到URP的光照改写与避坑指南

1. 从一次材质翻车说起：为什么内置管线的Shader搬到URP就废了

如果你是从内置管线（Built-in Render Pipeline）一路做过来的Unity开发者，大概率经历过这样一个场景：手里有一个调得好好的自定义光照Shader，模型质感、高光位置、阴影过渡都符合预期，结果项目一升级到URP（Universal Render Pipeline），同一个Shader贴上去，模型要么变成一片死黑，要么亮得像塑料玩具，高光位置完全对不上，阴影也糊成一团。你打开Shader代码一看，语法没报错，编译也通过了，但效果就是不对。

这不是你的Shader写错了，而是内置管线和URP在光照处理上的底层逻辑根本就是两套体系。内置管线用的是前向渲染路径下的多Pass光照模型，每个光源单独一个Pass，光照计算在Shader内部通过_WorldSpaceLightPos0、_LightColor0这些内置变量完成。而URP把光照计算从Shader里抽了出来，交给了统一的Lighting.hlsl库函数，Shader本身只需要负责表面属性（法线、粗糙度、金属度等），光照由管线统一调度。

这个差异带来的直接后果是：你在内置管线里写的所有光照相关代码，在URP里几乎全部要重写。不是改几个变量名的问题，而是整个光照计算的思路要换。我见过不少团队在这个环节上卡了整整一周，最后发现是光照方向的计算方式变了，导致法线贴图的效果完全错位。

这篇文章就是把这个坑彻底讲清楚。我会从光照模型的核心差异入手，拆解内置管线和URP在光照计算上的关键区别，然后给出具体的Shader改写方案和实操步骤。不管你是刚接触URP的新手，还是正在做管线迁移的老手，都能从里面找到可以直接抄作业的代码和避坑经验。

2. 光照模型的核心差异：从多Pass到单Pass的范式转移

2.1 内置管线的多Pass光照机制

内置管线的光照处理方式，理解起来其实很直观：每个光源一个Pass。假设场景里有一个平行光、两个点光源，那么一个受光照影响的Shader会被执行三次——平行光一次，每个点光源各一次。每次执行时，Unity会把当前光源的信息填入_WorldSpaceLightPos0、_LightColor0、_LightDirection等内置变量，Shader根据这些变量计算当前光源的贡献，然后把结果叠加到帧缓冲里。

这种方式的优点是逻辑清晰，每个Pass只关心一个光源，Shader代码写起来比较直观。但缺点也很明显：光源数量一多，Draw Call就爆炸。十个光源就是十次Pass，每个Pass都要重新计算一遍顶点变换和纹理采样，性能开销随光源数量线性增长。而且多Pass之间的混合是加法混合，容易出现过度曝光和光照溢出的问题。

在内置管线的Shader里，你通常会看到这样的结构：

Pass { Tags { "LightMode" = "ForwardBase" } // 处理主平行光 } Pass { Tags { "LightMode" = "ForwardAdd" } Blend One One // 处理额外光源 }

ForwardBase负责主光源和环境光，ForwardAdd负责其他逐像素光源。每个Pass里你都要自己写光照衰减、阴影采样、高光计算的代码。这套写法在Built-in里跑了十几年，资料多、教程多，但搬到URP就完全行不通了。

2.2 URP的单Pass多光源架构

URP的做法完全不同。它把所有光源的信息打包成一个数组，在单次Pass里统一处理。具体来说，URP在CPU端会把场景中影响该物体的光源数据（位置、方向、颜色、衰减参数等）整理好，通过StructuredBuffer或者常量缓冲区传给GPU。Shader里通过GetMainLight()和GetAdditionalLightsCount()、GetAdditionalLight()这些函数来获取光源信息。

这意味着什么呢？你的Shader不再需要关心有几个光源，也不需要写多个Pass。你只需要在片元着色器里调用URP提供的Lighting.hlsl中的光照函数，传入表面数据（法线、位置、粗糙度等），函数内部会自动遍历所有光源并累加贡献。

这种架构的好处是：

• Draw Call大幅降低：无论多少光源，都只在一个Pass里完成
• 光照计算统一：所有光源用同一套BRDF模型，不会出现不同Pass之间光照风格不一致的问题
• 扩展性强：新增光源类型（如聚光灯、区域光）只需要管线层面支持，Shader代码不用改

但代价是灵活性降低。在内置管线里你可以为每个光源单独定制光照模型，比如主光源用Blinn-Phong，点光源用Lambert。在URP里，所有光源走同一套PBR光照，你想改就得改管线源码或者用自定义的Lighting函数覆盖。

2.3 关键变量与函数的对照表

为了让你更直观地看到差异，我整理了一张内置管线和URP常用光照变量的对照表：

这张表里的每一行，都对应着一次实际迁移中必然会遇到的修改点。我见过有人只改了光源方向变量名，结果阴影完全不对，就是因为阴影衰减的获取方式也变了。

注意：URP的GetMainLight()返回的是一个Light结构体，包含direction、color、distanceAttenuation、shadowAttenuation等字段。这个结构体的定义在Lighting.hlsl里，不同URP版本可能有细微差异，建议直接打开包管理器里的URP源码查看当前版本的准确定义。

3. 逐像素光照计算：从手写公式到调用库函数

3.1 内置管线里的手写光照计算

在内置管线里写一个简单的漫反射Shader，你通常需要这样写：

// 顶点着色器里计算 float3 worldNormal = UnityObjectToWorldNormal(v.normal); float3 worldPos = mul(unity_ObjectToWorld, v.vertex).xyz; // 片元着色器里计算 float3 lightDir = normalize(_WorldSpaceLightPos0.xyz); float NdotL = saturate(dot(worldNormal, lightDir)); float3 diffuse = _LightColor0.rgb * NdotL * atten; float3 ambient = UNITY_LIGHTMODEL_AMBIENT.rgb; float3 finalColor = diffuse + ambient;

这段代码在内置管线里跑没问题，但搬到URP里，_WorldSpaceLightPos0和_LightColor0虽然还能编译通过（URP为了兼容保留了一些内置变量），但值可能是错的。因为URP的光源数据不再通过这些变量传递，而是通过Light结构体。你如果继续用旧变量，得到的光照方向可能是零向量或者上一个光源的残留值，导致光照完全错乱。

3.2 URP里的标准光照调用方式

URP的正确写法是这样的：

// 引入URP光照库 #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Lighting.hlsl" // 片元着色器里 float3 normalWS = normalize(input.normalWS); float3 positionWS = input.positionWS; // 获取主光源 Light mainLight = GetMainLight(); float NdotL = saturate(dot(normalWS, mainLight.direction)); float3 diffuse = mainLight.color * NdotL * mainLight.distanceAttenuation * mainLight.shadowAttenuation; // 获取环境光 float3 ambient = SampleSH(normalWS); // 处理额外光源 int additionalLightsCount = GetAdditionalLightsCount(); for (int i = 0; i < additionalLightsCount; i++) { Light light = GetAdditionalLight(i, positionWS); float NdotL = saturate(dot(normalWS, light.direction)); diffuse += light.color * NdotL * light.distanceAttenuation * light.shadowAttenuation; } float3 finalColor = diffuse + ambient;

这段代码和内置管线的版本相比，有几个关键变化：

第一，光源方向不再需要手动归一化。GetMainLight().direction返回的已经是归一化后的方向向量，你直接拿来做点积就行。内置管线里_WorldSpaceLightPos0对于平行光来说方向是反的（指向光源），需要取负或者调整，URP里统一成了从表面指向光源的方向，用起来更符合直觉。

第二，衰减和阴影合并到了Light结构体里。内置管线里你要分别处理距离衰减（通过_LightTexture0采样）和阴影衰减（通过SHADOW_ATTENUATION宏），URP把它们统一成了distanceAttenuation和shadowAttenuation两个字段，直接乘进去就行。

第三，额外光源需要手动遍历。内置管线里额外光源是通过多Pass自动处理的，你不需要写循环。URP里你必须自己写for循环遍历GetAdditionalLightsCount()，对每个光源调用GetAdditionalLight(i, positionWS)。这个循环的写法有讲究，后面会详细说。

3.3 逐像素光照的实操注意事项

在实际改写Shader的过程中，有几个地方特别容易出错，我一个个说。

第一个坑是法线空间。内置管线里你经常在顶点着色器里用UnityObjectToWorldNormal把法线转到世界空间，然后在片元着色器里直接用。URP里这个函数还能用，但更推荐用TransformObjectToWorldNormal，因为它在处理非统一缩放时更准确。如果你发现法线贴图的效果不对，先检查法线变换函数是不是用错了。

第二个坑是位置空间。URP的GetAdditionalLight需要传入世界空间的位置，如果你传的是对象空间或者裁剪空间的位置，光源方向会完全错乱。顶点着色器里记得用TransformObjectToWorld把顶点位置转到世界空间，然后插值到片元着色器。

第三个坑是额外光源的循环写法。URP的GetAdditionalLightsCount()返回的是当前物体受影响的额外光源数量，这个数量是管线根据光源的Render Mode和距离自动计算的。如果你在Shader里写死了循环次数，比如for (int i = 0; i < 4; i++)，那么当场景里只有两个额外光源时，后两次循环会拿到无效数据，导致光照异常。正确的做法是始终用GetAdditionalLightsCount()作为循环上界。

实操心得：在URP里调试光照问题时，可以临时把GetAdditionalLightsCount()的返回值输出到屏幕颜色上，看看管线实际传了几个光源过来。如果数量和你预期的不一样，检查一下光源的Render Mode是不是设成了Not Important，或者物体的Rendering Layer Mask有没有排除掉某些光源。

4. 阴影与环境光：URP里最容易被忽略的两个细节

4.1 阴影采样的差异与常见问题

内置管线里，阴影采样通常是通过SHADOW_ATTENUATION宏完成的，这个宏内部会根据当前Pass的类型（Base还是Add）和光源类型（平行光还是点光源）选择不同的阴影贴图和采样方式。你不需要关心阴影贴图是怎么生成的，只需要调用宏就行。

URP里阴影采样被封装得更彻底。GetMainLight()返回的Light结构体里已经包含了shadowAttenuation字段，你直接乘进去就行。但这里有一个非常容易踩的坑：GetMainLight()默认不接收阴影参数，如果你想要阴影效果，必须调用带参数的版本：

Light mainLight = GetMainLight(GetShadowCoord(positionWS));

GetShadowCoord会根据当前平台和光源类型计算阴影坐标，然后GetMainLight内部会用这个坐标去采样阴影贴图。如果你直接调用无参的GetMainLight()，shadowAttenuation会始终返回1，也就是没有阴影。

这个设计的好处是解耦了阴影计算和光照计算，你可以选择性地开启阴影。但坏处是新手很容易忘记传阴影坐标，然后纳闷为什么阴影不显示。

另外，URP的阴影距离和级联设置是在URP Asset里统一配置的，不像内置管线可以在Quality Settings里针对每个质量等级单独设置。如果你发现阴影在远处突然消失，或者近处阴影锯齿严重，需要去URP Asset的Shadows面板调整Max Distance和Cascade Count。

4.2 环境光与球谐光照的处理

内置管线里环境光通常通过UNITY_LIGHTMODEL_AMBIENT获取，这个值来自Lighting面板的Ambient设置。在URP里，环境光的获取方式变成了SampleSH(normalWS)，它采样的是球谐函数（Spherical Harmonics）计算出的环境光。

球谐光照的好处是它可以根据法线方向给出不同方向的环境光颜色，而不是一个统一的常量。比如天空是蓝色、地面是灰色的环境下，朝上的法线会偏蓝，朝下的法线会偏灰。这比内置管线的常量环境光真实得多。

但这里也有一个坑：SampleSH需要传入世界空间法线。如果你传的是对象空间法线，环境光的方向会跟着物体旋转，看起来就像环境光在跟着物体转，非常诡异。我见过有人因为这个原因，以为URP的环境光有Bug，折腾了半天才发现是法线空间搞错了。

还有一个细节是，URP的环境光强度可以在URP Asset里通过Environment Lighting的Intensity Multiplier调节。如果你从内置管线迁移过来，发现环境光太亮或太暗，先检查这个乘数是不是被改过。

4.3 阴影与环境光的联合调试技巧

在实际项目中，阴影和环境光的问题经常混在一起，导致你很难判断到底是哪个环节出了问题。我的经验是分步调试：

第一步，先把环境光关掉（在URP Asset里把Intensity Multiplier设为0），只保留主光源和阴影。如果这时候阴影正常，说明阴影采样没问题。

第二步，把主光源的阴影关掉（在光源组件里把Shadows设为No Shadows），只保留环境光。如果这时候环境光方向正确，说明球谐采样没问题。

第三步，两者都打开，检查叠加效果。如果出现阴影区域过暗或过亮，检查环境光是否在阴影区域也被正确采样。URP默认在阴影区域也会采样环境光，这符合物理规律，但如果你想要更风格化的效果，可以在Shader里手动降低阴影区域的环境光贡献。

注意：URP的阴影贴图默认使用屏幕空间阴影（Screen Space Shadows），这会导致一些在半透明物体上的阴影表现和内置管线不同。如果你的项目里有大量半透明材质，建议在URP Asset里关闭Screen Space Shadows，改用传统的阴影贴图采样。

5. 完整Shader改写实例：从Built-in到URP的逐步迁移

5.1 迁移前的内置管线Shader

假设我们有一个简单的Blinn-Phong光照Shader，内置管线版本如下：

Shader "Custom/BuiltinBlinnPhong" { Properties { _MainTex ("Texture", 2D) = "white" {} _SpecularPower ("Specular Power", Range(1, 100)) = 20 _SpecularIntensity ("Specular Intensity", Range(0, 2)) = 0.5 } SubShader { Tags { "RenderType" = "Opaque" } Pass { Tags { "LightMode" = "ForwardBase" } CGPROGRAM #pragma vertex vert #pragma fragment frag #include "UnityCG.cginc" #include "Lighting.cginc" struct appdata { float4 vertex : POSITION; float3 normal : NORMAL; float2 uv : TEXCOORD0; }; struct v2f { float4 pos : SV_POSITION; float2 uv : TEXCOORD0; float3 worldNormal : TEXCOORD1; float3 worldPos : TEXCOORD2; }; sampler2D _MainTex; float4 _MainTex_ST; float _SpecularPower; float _SpecularIntensity; v2f vert (appdata v) { v2f o; o.pos = UnityObjectToClipPos(v.vertex); o.uv = TRANSFORM_TEX(v.uv, _MainTex); o.worldNormal = UnityObjectToWorldNormal(v.normal); o.worldPos = mul(unity_ObjectToWorld, v.vertex).xyz; return o; } fixed4 frag (v2f i) : SV_Target { float3 normal = normalize(i.worldNormal); float3 lightDir = normalize(_WorldSpaceLightPos0.xyz); float3 viewDir = normalize(_WorldSpaceCameraPos - i.worldPos); float3 halfDir = normalize(lightDir + viewDir); float NdotL = saturate(dot(normal, lightDir)); float NdotH = saturate(dot(normal, halfDir)); float spec = pow(NdotH, _SpecularPower) * _SpecularIntensity; float3 albedo = tex2D(_MainTex, i.uv).rgb; float3 diffuse = albedo * _LightColor0.rgb * NdotL; float3 specular = _LightColor0.rgb * spec; float3 ambient = UNITY_LIGHTMODEL_AMBIENT.rgb * albedo; return fixed4(diffuse + specular + ambient, 1); } ENDCG } } }

这个Shader在内置管线里工作正常，但直接放到URP项目里，光照会完全错乱。

5.2 改写为URP版本的完整代码

下面是改写后的URP版本：

Shader "Custom/URPBlinnPhong" { Properties { _MainTex ("Texture", 2D) = "white" {} _SpecularPower ("Specular Power", Range(1, 100)) = 20 _SpecularIntensity ("Specular Intensity", Range(0, 2)) = 0.5 } SubShader { Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalPipeline" } Pass { Tags { "LightMode" = "UniversalForward" } HLSLPROGRAM #pragma vertex vert #pragma fragment frag #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl" #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Lighting.hlsl" struct appdata { float4 vertex : POSITION; float3 normal : NORMAL; float2 uv : TEXCOORD0; }; struct v2f { float4 pos : SV_POSITION; float2 uv : TEXCOORD0; float3 worldNormal : TEXCOORD1; float3 worldPos : TEXCOORD2; }; sampler2D _MainTex; float4 _MainTex_ST; float _SpecularPower; float _SpecularIntensity; v2f vert (appdata v) { v2f o; o.pos = TransformObjectToHClip(v.vertex); o.uv = TRANSFORM_TEX(v.uv, _MainTex); o.worldNormal = TransformObjectToWorldNormal(v.normal); o.worldPos = TransformObjectToWorld(v.vertex.xyz); return o; } half4 frag (v2f i) : SV_Target { float3 normal = normalize(i.worldNormal); float3 viewDir = normalize(GetWorldSpaceViewDir(i.worldPos)); float3 albedo = tex2D(_MainTex, i.uv).rgb; // 主光源 Light mainLight = GetMainLight(GetShadowCoord(i.worldPos)); float3 lightDir = mainLight.direction; float3 halfDir = normalize(lightDir + viewDir); float NdotL = saturate(dot(normal, lightDir)); float NdotH = saturate(dot(normal, halfDir)); float spec = pow(NdotH, _SpecularPower) * _SpecularIntensity; float3 diffuse = albedo * mainLight.color * NdotL * mainLight.distanceAttenuation * mainLight.shadowAttenuation; float3 specular = mainLight.color * spec * mainLight.shadowAttenuation; // 额外光源 int additionalLightsCount = GetAdditionalLightsCount(); for (int j = 0; j < additionalLightsCount; j++) { Light light = GetAdditionalLight(j, i.worldPos); float3 halfDirAdd = normalize(light.direction + viewDir); float NdotLAdd = saturate(dot(normal, light.direction)); float NdotHAdd = saturate(dot(normal, halfDirAdd)); float specAdd = pow(NdotHAdd, _SpecularPower) * _SpecularIntensity; diffuse += albedo * light.color * NdotLAdd * light.distanceAttenuation * light.shadowAttenuation; specular += light.color * specAdd * light.shadowAttenuation; } // 环境光 float3 ambient = SampleSH(normal) * albedo; return half4(diffuse + specular + ambient, 1); } ENDHLSL } } }

5.3 改写过程中的关键修改点解析

对比两个版本，有几个关键修改点需要特别注意。

第一，Shader标签变了。内置管线用Tags { "LightMode" = "ForwardBase" }，URP用Tags { "LightMode" = "UniversalForward" }。这个标签决定了Shader在URP的哪个阶段被执行，写错了会导致Shader完全不渲染。

第二，CGPROGRAM换成了HLSLPROGRAM。虽然两者语法基本兼容，但URP的库函数是用HLSL写的，用CGPROGRAM可能会遇到一些宏定义冲突。建议统一用HLSLPROGRAM。

第三，顶点变换函数变了。UnityObjectToClipPos换成了TransformObjectToHClip，mul(unity_ObjectToWorld, v.vertex)换成了TransformObjectToWorld。这些新函数在Core.hlsl里定义，内部处理了更多边界情况。

第四，光照计算完全重写。这是改动最大的部分。内置管线里直接操作_WorldSpaceLightPos0和_LightColor0，URP里通过GetMainLight()和GetAdditionalLight()获取光源数据。注意GetMainLight()的参数是阴影坐标，不传的话没有阴影。

第五，额外光源需要手动循环。内置管线里额外光源是自动多Pass处理的，URP里必须写for循环。循环里对每个光源都要重新计算高光和漫反射，不能只算漫反射。

第六，环境光从常量变成了球谐采样。UNITY_LIGHTMODEL_AMBIENT换成了SampleSH(normal)，需要传入世界空间法线。

实操心得：在改写过程中，建议先用一个最简单的漫反射Shader做验证，确认光源方向、颜色、衰减都正确后，再逐步加上高光、阴影、额外光源。一次性改完再调试，很容易因为多个问题叠加而找不到根源。

6. 常见问题与排查技巧实录

6.1 光照方向反了或高光位置不对

这是最常见的问题，通常有以下几个原因：

• 法线空间错误：检查TransformObjectToWorldNormal是否用在了正确的位置。如果你在顶点着色器里转了世界法线，片元着色器里直接normalize就行，不要再转一次。
• 光源方向取反：URP的GetMainLight().direction是从表面指向光源的方向，和内置管线的_WorldSpaceLightPos0方向相反。如果你从内置管线迁移过来，记得把点积的顺序调整一下。
• 视图方向计算错误：GetWorldSpaceViewDir返回的是从表面指向相机的方向，和内置管线的_WorldSpaceCameraPos - worldPos一致。如果你手动计算，注意不要搞反。

6.2 阴影不显示或显示异常

阴影问题通常集中在以下几个方面：

6.3 额外光源不生效或数量不对

额外光源的问题通常和光源设置有关：

• 光源的Render Mode设成了Not Important：这种光源不会被计入GetAdditionalLightsCount()，只会作为顶点光源或者SH光源处理。把它改成Important或Auto。
• URP Asset里的Additional Lights设成了Disabled：在URP Asset的Lighting面板里，把Additional Lights设为Per Pixel。
• 物体的Rendering Layer Mask排除了光源：检查光源的Rendering Layer Mask和物体的Rendering Layer Mask是否有交集。
• 循环上界写死了：始终用GetAdditionalLightsCount()作为循环上界，不要写死数字。

6.4 环境光过亮或过暗

环境光的问题通常和URP Asset的设置有关：

• Intensity Multiplier被改过：在URP Asset的Environment Lighting面板里检查这个值，默认是1。
• SampleSH传入了错误的空间法线：确保传入的是世界空间法线，不是对象空间。
• 环境光模式设置不当：URP支持Skybox、Gradient、Color三种环境光模式，不同模式下的球谐系数不同，检查是否选对了模式。

注意：如果你在Shader里同时使用了SampleSH和自定义的环境光颜色，可能会出现双重环境光叠加的问题。建议要么完全依赖SampleSH，要么完全自定义，不要混用。

7. 管线迁移的实操建议与性能考量

7.1 迁移前的准备工作

在开始迁移Shader之前，有几件事必须先做好：

第一，确认URP版本和Unity版本匹配。不同版本的URP在API上有细微差异，比如GetMainLight的参数在URP 10.x和12.x里就不完全一样。建议直接打开Package Manager查看当前URP版本的文档。

第二，备份所有自定义Shader。迁移过程中你可能会反复修改和回滚，没有备份会非常痛苦。建议用Git或者直接复制一份到项目外的文件夹。

第三，建立一个测试场景。场景里放一个球体、一个平面、一个平行光、两个点光源，用来验证光照、阴影、额外光源是否正常。这个场景在迁移过程中会反复用到。

7.2 性能对比与优化建议

URP的单Pass多光源架构在性能上通常优于内置管线的多Pass方案，但也有一些需要注意的地方：

• 额外光源的循环开销：虽然只有一个Pass，但循环里每个光源都要计算完整的BRDF，光源多了之后片元着色器的指令数会线性增长。建议在URP Asset里限制Additional Lights的最大数量，比如设为4。
• 阴影采样的开销：URP的阴影采样比内置管线更统一，但屏幕空间阴影在移动端可能有兼容性问题。如果目标平台是移动端，建议关闭屏幕空间阴影。
• 球谐环境光的开销：SampleSH的计算量很小，基本可以忽略。但如果你在片元着色器里多次调用，建议把结果缓存到一个变量里。

7.3 什么情况下值得迁移

不是所有项目都需要从内置管线迁移到URP。如果你的项目满足以下条件，迁移的收益会比较明显：

• 需要更好的移动端性能表现
• 需要Shader Graph的可视化编辑能力
• 需要统一的光照模型和后期处理栈
• 项目还在早期，没有大量依赖内置管线特性的自定义Shader

但如果你的项目已经深度依赖内置管线的多Pass光照，或者有大量手写的复杂光照Shader，迁移的成本可能会很高。这种情况下，可以考虑逐步迁移：先把新场景和新材质用URP，旧内容保持内置管线，通过渲染管线切换来过渡。

我个人在实际操作中的体会是，URP的光照体系虽然一开始需要适应，但一旦理解了Light结构体和Lighting.hlsl的设计思路，写Shader反而比内置管线更简洁。你不需要再关心光源数量、Pass混合、衰减纹理采样这些底层细节，可以把精力集中在材质表现本身。唯一需要警惕的是，URP的版本迭代比较快，API偶尔会有变动，建议在升级URP版本时先跑一遍光照测试场景，确认没有回归问题。