在WebGPU的计算管线里，存储纹理（Storage Texture）是GPUShader与CPU侧数据交互的重要通道。与普通采样纹理不同，存储纹理可以被compute shader直接写入甚至读写，而它的访问能力在API层面是用一个专门的字符串字面量联合类型来描述的，这就是GPUStorageTextureAccess。在TypeScript环境下把这个类型用对、用准，直接决定了你的bind group layout能否与WGSL代码对得上。
GPUStorageTextureAccess类型的完整定义
在官方的@webgpu/types包里，GPUStorageTextureAccess被定义为一组字符串字面量的联合。查看其.d.ts源码，大致形如：
type GPUStorageTextureAccess = | 'write-only' | 'read-only' | 'read-write';
注意这里的字符串用的是kebab-case（中划线分隔），不是驼峰。很多开发者凭直觉写成writeOnly，结果TypeScript直接抛出类型不匹配错误，提示字面量不在联合类型范围内。这是最常见的踩坑点之一。
三个成员各有明确的适用场景：write-only是最经典的用法，适用于输出渲染结果的compute pass；read-only允许shader只读取纹理内容，通常与GPUTextureUsage.TEXTURE_BINDING配合；read-write则要求纹理创建时必须带上STORAGE_BINDING用途标志，并且在部分早期实现中并不受支持，使用前需要通过navigator.gpu相关能力检测确认。
在Bind Group Layout中的类型标注实践
存储纹理访问类型真正发挥作用的位置是createBindGroupLayout的entry配置。一个典型的计算管线layout条目可以这样写：
const layout = device.createBindGroupLayout({
entries: [{
binding: 0,
visibility: GPUShaderStage.COMPUTE,
storageTexture: {
access: 'write-only',
format: 'rgba8unorm',
viewDimension: '2d',
},
}],
});这里的storageTexture.access字段类型就是GPUStorageTextureAccess。如果你希望显式标注类型而不是依赖类型推断，可以给配置对象加上类型注解，这样能获得更完整的编译期检查：
import type { GPUBindGroupLayoutEntry } from '@webgpu/types';
const entry: GPUBindGroupLayoutEntry = {
binding: 1,
visibility: GPUShaderStage.COMPUTE,
storageTexture: {
access: 'read-write',
format: 'rgba16float',
viewDimension: '2d',
},
};显式标注的好处在于，一旦字段名拼错（比如把storageTexture写成storageTextrue），TypeScript会立刻提示对象字面量可能只指定了已知属性，把隐患拦在编译期而不是运行时的WebGPU validation error。
与WGSL访问修饰符的对应关系
TypeScript侧的类型必须与WGSL代码里的纹理声明保持一致，否则管线创建阶段会报binding不匹配。对应关系如下：
'write-only'对应WGSL中的texture_storage_2d<rgba8unorm, write>'read-only'对应texture_storage_2d<rgba8unorm, read>'read-write'对应texture_storage_2d<rgba8unorm, read_write>
一个完整的WGSL compute shader写纹理的例子：
@group(0) @binding(0)
var outputTexture: texture_storage_2d<rgba8unorm, write>;
@compute @workgroup_size(8, 8)
fn main(@builtin(global_invocation_id) id: vec3<u32>) {
let color = vec4<f32>(1.0, 0.5, 0.2, 1.0);
textureStore(outputTexture, vec2<i32>(id.xy), color);
}需要特别留意的是format必须两边一致。TypeScript侧写rgba8unorm而WGSL侧声明成rgba8unorm-srgb，即便访问模式都对，验证依然会失败。这类错误的报错信息往往只提示binding conflict，定位起来比较费劲，所以建议把format定义成共享常量统一维护。
类型收窄与自定义帮助类型
在封装自己的WebGPU工具库时，经常需要对访问类型做进一步约束。比如你的管线只支持写入输出，可以定义一个收窄后的帮助类型：
type WriteOnlyAccess = Extract<GPUStorageTextureAccess, 'write-only'>;
interface StorageTextureEntry {
binding: number;
access: WriteOnlyAccess;
format: GPUTextureFormat;
viewDimension: GPUTextureViewDimension;
}这样任何传入'read-write'的调用点都会被TypeScript拒绝，从源头杜绝了不支持的访问模式进入配置。还可以结合判别联合，把format与access的合法组合编码进类型系统：
type StorageAccess =
| { access: 'read-write'; format: 'r32float' | 'rgba32float' }
| { access: 'write-only'; format: GPUTextureFormat };因为read-write模式对纹理格式有额外限制，只有部分浮点格式允许同时读写，把这条规则写进类型定义后，配置错误在IDE里就会以红色波浪线的形式直接暴露，省去了反复刷新浏览器看控制台报错的调试循环。
常见报错与排查思路
实际开发中最常见的三类问题：一是字符串拼写不符合kebab-case规范导致TS报错；二是纹理创建时漏掉了GPUTextureUsage.STORAGE_BINDING标志，运行时报usage不匹配；三是浏览器实现尚未开放read-write访问，需要做能力降级。前两类靠类型标注就能提前拦截，第三类则建议在初始化阶段检测navigator.gpu的适配器特征，准备一条write-only加中间纹理的备用路径。
把GPUStorageTextureAccess的类型体系理解透之后，bind group layout、纹理创建、WGSL声明这三处的访问模式就能始终保持一致，计算管线的配置也就不会再出现莫名其妙的validation error了。
TypeScriptWebGPU存储纹理修改时间：2026-09-04 06:54:33