Three.js v0.118.0后带阴影的ShaderMaterial编译失败

算力阿峰

2026-8-9

Three.js r118+顶点着色器编译失败修复方案

问题现象

升级到Three.js v0.118.0及之后版本，顶点着色器无法编译，控制台输出错误：

THREE.WebGLProgram: shader error: 0 35715 false gl.getProgramInfoLog Vertex shader is not compiled.
THREE.WebGLShader: gl.getShaderInfoLog() vertex
ERROR: 0:197: 'transformedNormal' : undeclared identifier
ERROR: 0:197: 'inverseTransformDirection' : no matching overloaded function found
ERROR: 0:197: '=' : dimension mismatch
ERROR: 0:197: '=' : cannot convert from 'const mediump float' to 'highp 3-component vector of float'

报错原因

从r118开始，Three.js调整了内置顶点着色器的变量注入规则和函数签名：

transformedNormal不再作为内置变量自动提供，需要手动声明计算
inverseTransformDirection的参数类型要求更严格，维度不匹配会触发报错

具体修复步骤

手动添加transformedNormal的定义
在顶点着色器中，替换原来直接使用transformedNormal的代码，手动计算视图空间下的法线：
```
// 替换原代码中直接调用transformedNormal的部分
vec3 transformedNormal = normalize(normalMatrix * objectNormal);
```
说明：objectNormal是r118+保留的内置变量，代表模型空间原始法线；normalMatrix是内置的法线变换矩阵，用于将法线转换到视图空间。
修正inverseTransformDirection函数调用
检查第197行的函数调用，确保传入参数为3维方向向量和4x4变换矩阵。例如将视图空间法线转换为世界空间的正确调用：
```
vec3 worldNormal = inverseTransformDirection(transformedNormal, viewMatrix);
```
确认你传入的第一个参数是3维向量，第二个参数是对应的变换矩阵（如viewMatrix或modelMatrix），避免维度不匹配。