TypeScript中如何定义WebGPU Shader Stage API的着色器阶段标志并实现顶点片元计算组合使用

在WebGPU应用开发中，着色器阶段（Shader Stage）决定了某段WGSL代码是在顶点处理、片元处理还是计算调度中执行。WebGPU通过GPUShaderStage这一包含比特标志的常量对象来标记阶段，而在TypeScript项目中如果仅用普通数字传参，编译器无法帮我们检查是否传入了非法的阶段组合。因此，利用TypeScript的类型系统来重新定义这些标志，并支持顶点、片元、计算以及它们的任意组合，是构建健壮渲染管线的第一步。

WebGPU着色器阶段标志的底层定义与TypeScript现状

根据WebGPU标准，GPUShaderStage是一个包含VERTEX、FRAGMENT、COMPUTE三个属性的对象，它们的值分别是1、2、4，也就是典型的按位枚举（bitmask）。在渲染管线中，我们可以通过按位或运算将多个阶段合并，例如GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT表示一段WGSL同时用于顶点和片元阶段。这种设计的优势是单个数值就能表达多种能力，且判断某个阶段是否包含时用按位与即可。

然而在TypeScript原生环境下，GPUShaderStage的类型声明通常只是{ VERTEX: number; FRAGMENT: number; COMPUTE: number }，而接收阶段参数的接口（如GPUShaderModule的compilationInfo或GPUPipelineLayout相关描述）往往将字段类型标为number。这就导致开发者写下0b1000或8这类未定义的值时，TypeScript不会报错，但浏览器会忽略或抛异常。我们需要更精确的类型来描述“只能是这几个比特组合”的约束。

一种朴素的修正方式是使用类型别名限制取值，但由于位运算结果在TypeScript中会被拓宽为number，单纯靠类型别名无法在编译期验证组合合法性。因此更实用的方案是借助枚举、const断言对象以及字面量联合类型，把阶段标志变成有语义的单位，同时在代码层面提供组合辅助函数，既保留比特操作的灵活性，又获得编辑器智能提示。

使用TypeScript枚举与类型别名定义安全阶段标志

我们可以创建一个枚举来表达各个阶段，并利用TypeScript的const enum或普通枚举保证值与原生规范一致。下面代码展示如何定义以及如何使用按位组合：

// 定义与 WebGPU 规范一致的着色器阶段标志
const enum ShaderStage {
  Vertex = 1 << 0,   // 1
  Fragment = 1 << 1, // 2
  Compute = 1 << 2   // 4
}

// 类型别名：合法的阶段标志只能是这三个枚举值的按位组合
type ShaderStageFlags = ShaderStage | number;

// 组合辅助函数，确保语义清晰且避免手写魔法数字
function combineStages(...stages: ShaderStage[]): number {
  return stages.reduce((acc, cur) => acc | cur, 0);
}

const vsFs = combineStages(ShaderStage.Vertex, ShaderStage.Fragment);
console.log(vsFs === (ShaderStage.Vertex | ShaderStage.Fragment)); // true

上面的combineStages函数接收一个阶段数组并归约出组合值。相比直接写ShaderStage.Vertex | ShaderStage.Fragment，函数式写法在需要动态决定阶段时更安全，也能集中处理校验逻辑。如果传入了不在枚举中的数值，TypeScript会因为类型不匹配而提示，因为参数类型被限制为ShaderStage。

为了进一步在类型层面禁止非法组合，我们可以放弃宽泛的number，改用模板字面量或联合类型描述已知组合。但对于通用渲染库来说，阶段组合可能非常多，穷举联合类型不现实。折中方案是导出一个isShaderStage类型守卫函数，在运行时配合断言，既照顾类型也照顾运行安全。下面示例展示类型守卫：

function isShaderStage(value: number): value is ShaderStage {
  const valid = ShaderStage.Vertex | ShaderStage.Fragment | ShaderStage.Compute;
  // 检查 value 仅由合法比特位构成
  return (value & ~valid) === 0 && value !== 0;
}

const stage = combineStages(ShaderStage.Vertex, ShaderStage.Compute);
if (isShaderStage(stage)) {
  // 此处 stage 被收窄为 ShaderStage 类型
  console.log('合法阶段组合:', stage);
}

通过这种定义，我们在TypeScript侧拥有了一套对齐WebGPU原生常量、且能组合使用的阶段标志体系。接下来看看如何将它应用到真实的GPUDevice管线创建流程中，包括纯计算管线和图形管线的不同配置。

在WebGPU管线创建中应用阶段标志与组合实践

WebGPU的createRenderPipeline和createComputePipeline都依赖阶段标志来绑定着色器模块。对于图形管线，顶点状态必须包含Vertex阶段，而片元状态可选但一旦提供，其入口对应的模块就需要Fragment标志。下面代码演示一个同时使用顶点与片元着色器的渲染管线描述：

const device: GPUDevice = await navigator.gpu.requestAdapter()
  .then(a => a!.requestDevice());

const shaderCode = `
@vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4<f32> {
  return vec4<f32>(0.0, 0.0, 0.0, 1.0);
}
@fragment fn fs() -> @location(0) vec4<f32> {
  return vec4<f32>(1.0, 0.0, 0.0, 1.0);
}
`;

const module = device.createShaderModule({ code: shaderCode });

const renderPipeline = device.createRenderPipeline({
  layout: 'auto',
  vertex: {
    module,
    entryPoint: 'vs',
    // 此处阶段由 vertex 固定使用 Vertex 标志，无需手动传
  },
  fragment: {
    module,
    entryPoint: 'fs',
    targets: [{ format: 'bgra8unorm' }],
  },
  primitive: { topology: 'triangle-list' },
});

在上面的渲染管线中，虽然我们没有显式写GPUShaderStage.VERTEX，但WebGPU规范规定vertex字段隐含顶点阶段，fragment字段隐含片元阶段。当我们把同一个module同时用于两个字段时，就等价于阶段标志的组合。如果我们在createShaderModule之外单独用GPUShaderStage做可见性控制（比如向绑定组布局声明某缓冲区可用于顶点和片元），就必须手动组合：

const bindGroupLayout = device.createBindGroupLayout({
  entries: [{
    binding: 0,
    visibility: ShaderStage.Vertex | ShaderStage.Fragment,
    buffer: { type: 'uniform' }
  }]
});

对于计算管线，阶段标志就只剩Compute。但有些项目会抽象出统一的“管线描述符构造器”，根据传入的阶段标志自动决定创建渲染还是计算管线。此时我们之前定义的combineStages和isShaderStage就能派上用场：若标志包含Compute且不含图形阶段，走计算分支；若包含Vertex或Fragment，走图形分支。这样在TypeScript层就把WebGPU着色器阶段的数据类型与组合使用方式收敛为一套可维护的API，既减少运行时错误，也提升代码可读性。

TypeScriptWebGPUshader_stage修改时间：2026-08-18 09:26:37