Chapter 98: WebGPU Device Queue and Pipeline Model

WebGPU 的主问题是：浏览器中的 JavaScript 如何把一帧图像描述成 GPU 能执行的资源、管线和命令，并把这些命令提交到设备队列。读完本章后，读者应能定位一次 WebGPU 绘制卡在 adapter/device 获取、资源创建、pipeline layout、bind group、command encoding、queue submit 或 shader 接口中的哪一层。

本章使用一个贯穿材料：在 canvas 中绘制一个带颜色的三角形，并用一个 uniform buffer 提供二维位移。这个例子足够小，可以暴露 WebGPU 的核心对象：GPUAdapter 代表浏览器可用的物理 GPU/驱动组合，GPUDevice 代表当前页面拿到的逻辑设备，GPUQueue 负责接收已经编码好的命令，GPURenderPipeline 固定 shader、顶点布局、颜色目标和 primitive state，GPUBindGroup 把 buffer、texture、sampler 放到 shader 能访问的位置。

WebGPU 的工程收益来自显式结构。WebGL 时代，很多状态通过上下文对象隐式累积；WebGPU 把资源用途、绑定布局、shader 接口、render pass attachment 和提交边界提前描述出来。浏览器可以在创建对象和提交命令时做验证，也可以把底层 Vulkan、Metal 或 Direct3D 12 的差异收束到统一模型中。MDN WebGPU API 将 WebGPU 描述为面向高性能计算和复杂图像绘制的浏览器 GPU API，并强调其设备访问、pipeline、shader、command queue 和错误处理路径。

本章只讲 WebGPU 基础渲染路径。Compute pipeline、storage buffer、indirect draw 和 timestamp query 的组合会在后续章节展开；这里先建立一条稳定判断链：requestAdapter → requestDevice → 创建资源 → 创建 pipeline → 编码 render pass → queue.submit → 浏览器呈现当前 swapchain texture。

98.1 WebGPU 与 WebGL 的差异与优势

WebGPU 与 WebGL 的第一层差异是 API 对 GPU 工作的描述方式。WebGL 接近 OpenGL ES 的状态机模型，调用顺序会持续改变当前上下文状态；WebGPU 接近现代显式图形 API 的描述符模型，核心对象在创建时就写明用途、布局和阶段可见性。三角形例子中，顶点 buffer 通过 GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST 声明用途，uniform buffer 通过 bind group layout 声明在 vertex stage 可见，pipeline 通过 descriptor 固定 shader entry point 和 color target format。

这种差异改变了错误出现的位置。WebGL 常见错误在 draw call 附近暴露，例如当前 program、attribute、uniform 或 texture unit 状态缺失。WebGPU 会把一部分错误提前到对象创建和命令编码阶段：buffer usage 与后续操作不匹配会触发验证错误；bind group layout 与 WGSL 中 @group、@binding 不一致会让 pipeline 或 bind group 无法通过验证；render pass 的 color attachment format 与 pipeline 的 fragment target format 不一致会导致命令无效。

维度	WebGL	WebGPU	对三角形例子的影响
设备入口	canvas.getContext("webgl") 获取状态机上下文	navigator.gpu.requestAdapter() 后再 adapter.requestDevice()	先拿逻辑设备，再配置 webgpu canvas context
资源用途	多数资源用途由绑定点和调用语义决定	GPUBufferUsage、GPUTextureUsage 在创建时声明	顶点数据和 uniform 数据需要带正确 usage flags
Shader 语言	GLSL ES	WGSL	shader 接口通过 @location、@builtin、@group、@binding 显式连接
绑定模型	attribute、uniform location、texture unit 分散设置	bind group layout 与 bind group 集中描述资源接口	uniform buffer 绑定到 group 0 binding 0，并由 pipeline layout 约束
命令提交	draw 调用直接进入上下文命令流	command encoder 记录后提交到 queue	一帧先编码 render pass，再 device.queue.submit
计算能力	主要面向图形，GPGPU 依赖扩展或纹理技巧	render pipeline 与 compute pipeline 同属核心模型	当前章用 render pipeline，后续可复用 device/queue/bind group 结构进入 compute
浏览器安全	WebGL 也有沙箱和验证	WebGPU 的资源访问、shader、错误作用域和设备丢失路径更显式	页面拿到的是隔离的 logical device，错误通过 validation/error scope/device lost 暴露

WebGPU 的优势来自更早的结构化描述。pipeline descriptor 把 vertex shader、fragment shader、顶点输入布局、primitive state、color target format 和 bind group layout 组合到一个不可变对象中。浏览器实现可以据此预先编译底层 pipeline state，渲染循环中只切换已经创建好的对象。对于同一个三角形，每帧变化的是 uniform buffer 中的位移值和当前 canvas texture；pipeline 本身应复用。

浏览器安全模型也影响 API 形态。网页代码无法直接拿到底层 GPU 指针，也无法跳过用户代理的验证。WebGPU 在安全上下文中暴露，通常要求 HTTPS；设备能力通过 adapter/device 的 features 与 limits 查询。跨浏览器、跨系统时，正确做法是先查询能力，再决定是否启用特性、格式和资源规模。当前章例子只依赖基础 render pipeline，因此把兼容重点放在 navigator.gpu 存在性、adapter 获取、preferred canvas format 和 device lost 处理上。

这条差异链给出一个工程判断：WebGPU 程序的稳定性来自“创建期描述清楚、帧循环期少改状态”。绘制一个三角形时，setup 阶段创建 device、buffers、bind group、pipeline；frame 阶段只写入小块数据、获取当前 swapchain texture、编码 draw、提交 queue。把这两类工作混在每帧中，会增加 CPU 验证、对象分配和 pipeline 编译成本。

98.2 WebGPU 渲染管线架构

WebGPU 渲染管线可以按两条路径理解：一条是对象创建路径，负责把资源和 pipeline 准备好；另一条是帧执行路径，负责把当前帧的命令编码并交给 queue。三角形例子中，顶点 buffer、uniform buffer、shader module、bind group layout、bind group 和 render pipeline 属于对象创建路径；getCurrentTexture()、beginRenderPass()、draw() 和 queue.submit() 属于帧执行路径。

下面的图描述一帧从 JavaScript 输入到 GPU 执行的最小路径。它省略浏览器进程与驱动内部线程，只保留 WebGPU 编程时必须能定位的对象边界。

图中的关键分界是 CommandBuffer。在调用 finish() 之前，JavaScript 只是在 command encoder 上记录命令；调用 device.queue.submit() 之后，命令进入设备队列，由浏览器实现和底层图形 API 安排执行。queue.submit() 返回时，语义只覆盖命令已经提交到队列；GPU 完成当前帧需要额外同步证据。需要读取结果、复用临时资源或测量执行时间时，才需要额外的同步或查询机制。

渲染管线的核心对象是 GPURenderPipeline。它由 device.createRenderPipeline() 创建，输入是一份 descriptor。descriptor 中的 vertex 部分指定 shader module、entry point 和 vertex buffer layout；fragment 部分指定 shader module、entry point 和 color target format；primitive 部分指定 topology、front face、cull mode 等状态；layout 部分指定 bind group layout。这个对象相当于“GPU 如何解释 draw call”的固定合同。

GPUBindGroup 负责把 shader 声明的资源接口与真实资源连接起来。WGSL 中的 @group(0) @binding(0) 只声明 shader 期待一个资源槽；bind group layout 声明这个槽的资源类型、阶段可见性和访问方式；bind group 把具体 GPUBuffer 放入这个槽。三角形的位移 uniform 因此需要三处一致：WGSL 声明、bind group layout 条目、bind group resource。

Render pass 则定义当前 draw 写入哪里以及怎样处理 attachment。对屏幕绘制来说，每帧都从 GPUCanvasContext.getCurrentTexture() 取得当前 swapchain texture，再创建 texture view 放进 colorAttachments。loadOp: "clear" 表示 pass 开始时清空目标，storeOp: "store" 表示 pass 结束后保存结果供浏览器呈现。若画面只出现清屏色，说明 render pass 已经运行到 attachment 清除，后续 draw 路径或 pipeline/resource 绑定路径需要检查。

一条可复用的排查顺序是：先确认 device 和 context 配置成功，再确认 pipeline 的 color format 与 context format 一致，然后确认 shader entry point、vertex layout、bind group layout 与实际资源一致，最后检查帧循环是否执行了 setPipeline、setVertexBuffer、setBindGroup、draw、end、finish 和 submit。这个顺序从 API 对象边界向 draw call 收敛，可以快速区分“没有拿到 GPU”“没有写入目标”“没有有效 draw”“shader 接口不匹配”这几类问题。

98.3 Shader 语言 WGSL 的特点与使用方法

WGSL（WebGPU Shading Language）是 WebGPU 在 Web 平台上的规范 shader 语言。W3C 的 WGSL Candidate Recommendation Draft 把它定义为 WebGPU 的 shading language；截至 2026-06-07，该文档仍处在持续维护状态。WGSL 的工作位置是 pipeline 内部：JavaScript 创建 shader module，pipeline descriptor 指定 entry point，GPU 在对应 stage 执行这些 entry point。

WGSL 的可读性来自显式接口。Vertex shader 的输入属性通过 @location 与 vertex buffer layout 连接，输出裁剪空间位置通过 @builtin(position) 交给固定功能光栅化阶段，fragment shader 的颜色输出通过 @location(0) 写入 color target。资源绑定通过 @group 和 @binding 对齐 bind group layout。三角形例子中，位移 uniform 属于 group 0 binding 0，顶点 position 与 color 属于 location 0 和 location 1。

下面的 WGSL 代码展示最小接口。它的目的在于写清顶点 buffer、uniform buffer、vertex stage、fragment stage 和 color target 的连接关系，复杂光照不属于当前示例范围。

struct Uniforms {
  offset: vec2f,
  padding: vec2f,
};

@group(0) @binding(0)
var<uniform> uniforms: Uniforms;

struct VertexIn {
  @location(0) position: vec2f,
  @location(1) color: vec3f,
};

struct VertexOut {
  @builtin(position) clip_position: vec4f,
  @location(0) color: vec3f,
};

@vertex
fn vertex_main(input: VertexIn) -> VertexOut {
  var output: VertexOut;
  let shifted = input.position + uniforms.offset;
  output.clip_position = vec4f(shifted, 0.0, 1.0);
  output.color = input.color;
  return output;
}

@fragment
fn fragment_main(input: VertexOut) -> @location(0) vec4f {
  return vec4f(input.color, 1.0);
}

这段 shader 对应的 CPU 侧合同有三条。第一，vertex buffer layout 中 shaderLocation: 0 的格式要能提供 vec2f，shaderLocation: 1 的格式要能提供 vec3f。第二，uniform buffer 的字节布局要满足 WGSL 对 uniform address space 的对齐要求；示例使用 offset 加 padding，让结构大小保持到 16 字节边界。第三，pipeline 的 fragment target format 要与 canvas context 的 format 一致，否则 fragment shader 输出无法合法写入当前颜色附件。

WGSL 的强验证会把部分问题提前暴露。入口函数标记必须与 pipeline stage 对应，vertex stage 应使用 @vertex，fragment stage 应使用 @fragment，compute stage 应使用 @compute。资源访问的地址空间和访问模式也要匹配，例如 uniform buffer 用 var<uniform>，storage buffer 用 var<storage> 并声明访问方式。浏览器会在 shader module 创建、pipeline 创建或命令验证时报告不一致处。

WGSL 与 JavaScript 的接口边界应通过小表格固定下来。对于当前三角形，最小合同如下。

WGSL 声明	CPU 侧对象	检查点
@location(0) position: vec2f	vertex buffer attribute shaderLocation: 0, format: "float32x2"	stride 和 offset 与 typed array 排列一致
@location(1) color: vec3f	vertex buffer attribute shaderLocation: 1, format: "float32x3"	每个顶点颜色从正确字节偏移开始
@builtin(position)	固定功能裁剪与光栅化阶段	输出必须是 clip space vec4f
@group(0) @binding(0)	bind group layout entry 0 与 bind group entry 0	buffer 类型、阶段可见性和绑定编号一致
@location(0) vec4f fragment output	render pipeline color target 0	target format 与 context format 一致

使用 WGSL 时，排查重点从“shader 是否能编译”扩展到“shader 接口是否和 host descriptor 完整相等”。WebGPU 的 pipeline 是接口合同，WGSL 只是合同的一侧；另一侧由 vertex buffer layout、bind group layout、pipeline layout 和 render pass attachment 共同完成。

98.4 创建 WebGPU 渲染基础结构

创建 WebGPU 渲染基础结构可以分成四步：访问设备、配置画布、创建资源和 pipeline、在帧循环中编码命令。当前章的三角形例子采用最小版本，省略 asset loader、纹理、深度缓冲、多 pipeline 缓存和 resize 管理细节，只保留能解释 device/queue/pipeline 模型的路径。

第一步是访问 adapter 和 device，并配置 webgpu context。navigator.gpu 是浏览器暴露的入口；adapter 表示当前环境可用的 GPU/驱动后端；device 是页面实际使用的逻辑设备。getPreferredCanvasFormat() 返回当前浏览器和设备推荐的画布格式，后续 pipeline 的 fragment target 必须使用同一个 format。

async function createWebGpuBase(canvas) {
  if (!navigator.gpu) {
    throw new Error("WebGPU is unavailable in this browser context.");
  }

  const adapter = await navigator.gpu.requestAdapter({
    powerPreference: "high-performance",
  });
  if (!adapter) {
    throw new Error("No WebGPU adapter was returned.");
  }

  const device = await adapter.requestDevice();
  const context = canvas.getContext("webgpu");
  const format = navigator.gpu.getPreferredCanvasFormat();

  context.configure({
    device,
    format,
    alphaMode: "premultiplied",
  });

  return { adapter, device, context, format };
}

这段代码回答“当前页面有没有可用逻辑设备”。它没有承诺任何高级特性可用；后续要使用 timestamp query、storage texture、f16 或更高资源 limits 时，应从 adapter.features、device.features 和 adapter.limits 读取证据。基础三角形只依赖 core render pipeline，因此在没有额外 feature 的情况下也能设计出稳定路径。

第二步是创建顶点 buffer、uniform buffer、bind group layout 和 bind group。顶点数组中每个顶点包含 position.xy 与 color.rgb，共 5 个 f32，所以 stride 是 20 字节。uniform buffer 使用 16 字节大小，其中前 8 字节放 offset.xy，后 8 字节作为 padding。

function createTriangleResources(device) {
  const vertices = new Float32Array([
     0.0,  0.6, 1.0, 0.2, 0.1,
    -0.6, -0.5, 0.1, 0.8, 0.2,
     0.6, -0.5, 0.2, 0.4, 1.0,
  ]);

  const vertexBuffer = device.createBuffer({
    size: vertices.byteLength,
    usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
  });
  device.queue.writeBuffer(vertexBuffer, 0, vertices);

  const uniformBuffer = device.createBuffer({
    size: 16,
    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
  });

  const bindGroupLayout = device.createBindGroupLayout({
    entries: [
      {
        binding: 0,
        visibility: GPUShaderStage.VERTEX,
        buffer: { type: "uniform" },
      },
    ],
  });

  const bindGroup = device.createBindGroup({
    layout: bindGroupLayout,
    entries: [
      {
        binding: 0,
        resource: { buffer: uniformBuffer },
      },
    ],
  });

  return { vertexBuffer, uniformBuffer, bindGroupLayout, bindGroup };
}

这里的资源 usage 是后续命令合法性的前提。writeBuffer 需要目标 buffer 带 COPY_DST，顶点输入需要 VERTEX，uniform 绑定需要 UNIFORM。如果 usage 少写，问题会在写入、绑定或提交附近暴露；排查时应回到 buffer 创建处检查 usage flags。

第三步是创建 shader module 和 render pipeline。示例使用显式 bind group layout，这样 WGSL 中的 group/binding 与 CPU 侧 layout 对齐关系可见。生产工程中可以使用 layout: "auto" 降低样板代码，但调试资源接口时，显式 layout 更适合定位错误。

function createTrianglePipeline(device, format, shaderCode, bindGroupLayout) {
  const shaderModule = device.createShaderModule({ code: shaderCode });

  const pipelineLayout = device.createPipelineLayout({
    bindGroupLayouts: [bindGroupLayout],
  });

  const pipeline = device.createRenderPipeline({
    layout: pipelineLayout,
    vertex: {
      module: shaderModule,
      entryPoint: "vertex_main",
      buffers: [
        {
          arrayStride: 20,
          attributes: [
            { shaderLocation: 0, offset: 0, format: "float32x2" },
            { shaderLocation: 1, offset: 8, format: "float32x3" },
          ],
        },
      ],
    },
    fragment: {
      module: shaderModule,
      entryPoint: "fragment_main",
      targets: [{ format }],
    },
    primitive: {
      topology: "triangle-list",
    },
  });

  return pipeline;
}

这段 pipeline descriptor 将前面三节的合同落到一个对象上。entryPoint 必须找到 WGSL 中带对应 stage attribute 的函数；vertex buffer layout 必须覆盖 shader 使用的 locations；fragment target format 必须等于 context configure 使用的 format；layout 必须容纳 shader 使用的 bind group。三角形缺失时，这四项是 pipeline 层的主要检查点。

第四步是每帧更新 uniform、编码 render pass 并提交队列。GPUQueue.writeBuffer() 适合写入小块、频繁更新的数据，例如当前例子的二维位移。命令编码完成后，finish() 产出 GPUCommandBuffer，queue.submit() 把命令交给设备队列。

function drawFrame(device, context, pipeline, vertexBuffer, uniformBuffer, bindGroup, timeSeconds) {
  const offset = new Float32Array([
    Math.sin(timeSeconds) * 0.15,
    Math.cos(timeSeconds) * 0.10,
    0.0,
    0.0,
  ]);
  device.queue.writeBuffer(uniformBuffer, 0, offset);

  const commandEncoder = device.createCommandEncoder();
  const textureView = context.getCurrentTexture().createView();

  const pass = commandEncoder.beginRenderPass({
    colorAttachments: [
      {
        view: textureView,
        clearValue: { r: 0.02, g: 0.03, b: 0.05, a: 1.0 },
        loadOp: "clear",
        storeOp: "store",
      },
    ],
  });

  pass.setPipeline(pipeline);
  pass.setVertexBuffer(0, vertexBuffer);
  pass.setBindGroup(0, bindGroup);
  pass.draw(3);
  pass.end();

  device.queue.submit([commandEncoder.finish()]);
}

这段帧循环说明 queue 的角色：queue 接收已经完成编码的 command buffer，也承担部分数据上传入口，例如 writeBuffer。它承担提交边界；draw 命令属于 pass encoder，submit 属于队列。把这两个层级分清后，WebGPU 的调用顺序就变成可检查路径：写入本帧数据 → 获取当前纹理 → 编码 pass → 设置 pipeline 和资源 → draw → 结束 pass → submit。

实际工程还要处理 resize 和 device lost。resize 时，应根据 canvas 的显示尺寸和 device pixel ratio 更新 canvas width/height，并重新配置 context；device lost 时，应停止使用旧 device 相关资源，重新申请 device 并重建资源对象。当前章三角形不展开恢复流程，但要保留这个边界：GPUDevice 的有效期受浏览器、驱动重置、系统休眠和资源压力影响，这些条件都可能触发设备丢失。

98.5 性能考量与调试方案

WebGPU 基础程序的性能判断应先分层。adapter/device 获取和 pipeline 创建属于初始化成本；buffer 写入、命令编码、render pass 提交属于每帧 CPU 成本；shader 执行、顶点读取、fragment 写入和 attachment 存储属于 GPU 成本。三角形例子很小，瓶颈更常出现在每帧重复创建 pipeline、bind group、buffer 或 shader module 带来的 CPU 验证与对象分配成本。

第一条性能规则是复用稳定对象。GPUDevice、shader module、pipeline layout、render pipeline、bind group layout、静态 vertex buffer 和大部分 bind group 应在初始化阶段创建。帧循环中只更新确实变化的数据，例如 uniform buffer 的 16 字节位移。若每帧调用 createRenderPipeline()，浏览器可能反复执行 shader 编译、layout 推导、descriptor 验证和底层 pipeline 创建，帧时间会出现尖峰。

第二条规则是减少 JavaScript 与 GPU 的小粒度交互。queue.writeBuffer() 很适合上传小块 uniform 数据；大量顶点、纹理或动态资源应批量组织，使用 staging、ring buffer 或按帧资源池管理。WebGPU 的安全验证会检查资源 usage、范围、对齐和绑定状态；小而碎的调用会放大 CPU 端调度与验证开销。当前例子只上传 16 字节 uniform，属于合理范围。

第三条规则是控制 submit 粒度。一个页面可以在一帧中提交多个 command buffer，但每次提交都有调度成本。基础渲染路径通常把一帧相关 render pass 编码到少量 command buffer 中提交。需要分多次 submit 的典型场景是跨队列同步、读回结果、外部调度或特殊依赖；基础三角形没有这类依赖，因此一次 queue.submit([commandEncoder.finish()]) 足够。

第四条规则是把颜色格式、load/store 和 attachment 数量纳入带宽判断。navigator.gpu.getPreferredCanvasFormat() 给出适合当前平台的 canvas format，pipeline target 应与它一致。loadOp: "clear" 会把 pass 开始语义固定为清屏，storeOp: "store" 会保留结果用于呈现。复杂场景中，多 render target、MSAA resolve、深度纹理和后处理纹理会显著提高 bandwidth 压力；当前章只使用一个颜色附件，便于把问题定位到 pipeline 和资源接口。

调试 WebGPU 时，应先使用 API 自带的错误路径。pushErrorScope() 和 popErrorScope() 可以捕获一段创建或编码操作中的 validation/out-of-memory/internal error；device.lost 可以处理设备丢失。下面的代码适合包住 pipeline 创建，确认错误来自 shader、layout 或 target format。

async function createPipelineWithValidation(device, createPipeline) {
  device.pushErrorScope("validation");
  const pipeline = createPipeline();
  const error = await device.popErrorScope();

  if (error) {
    console.error("WebGPU validation error:", error.message);
    return null;
  }

  return pipeline;
}

这段代码回答“pipeline 创建阶段是否通过验证”。如果错误为空而画面仍无三角形，排查应进入帧执行路径：确认 render pass clear 是否可见、确认 setPipeline 和 draw(3) 是否执行、确认 vertex buffer 数据和 stride/offset 是否一致、确认 uniform offset 是否把三角形移动到视口外。若 canvas 只显示清屏色，说明 context 和 render pass 至少部分有效；若 canvas 完全无输出，则先检查 context configure、尺寸、CSS 显示和浏览器安全上下文。

浏览器工具适合观察更靠近运行时的证据。Chrome、Firefox 和 Safari 的 WebGPU 调试能力在版本间变化较快，工具名称、面板位置和捕获粒度需要按当前浏览器确认。可迁移的观察问题保持稳定：本帧是否提交了 command buffer，render pass attachment 是哪个 texture view，pipeline target format 是否匹配，bind group 中的 buffer 是否有正确 usage，shader module 是否有验证日志，设备是否触发 lost。工具只是观察入口，结论仍应回到 WebGPU 对象边界。

一套稳定的排查顺序如下：

• 先检查运行环境：HTTPS、安全上下文、navigator.gpu、adapter、device、context configure 和 canvas 实际像素尺寸。
• 再检查资源创建：buffer size、usage flags、typed array 字节数、uniform 对齐、context format 和 texture view。
• 接着检查接口合同：WGSL entry point、@location、@group、@binding、bind group layout、pipeline layout 和 target format。
• 然后检查帧命令：writeBuffer、beginRenderPass、setPipeline、setVertexBuffer、setBindGroup、draw、end、finish、queue.submit。
• 最后检查性能症状：每帧对象创建、过多 submit、碎片化上传、过多 attachment、shader 分支、纹理采样和浏览器主线程阻塞。

这套顺序把 WebGPU 的显式模型转成排查动作。对当前三角形来说，能看到清屏色却没有图形时，优先检查 pipeline 和 draw 相关状态；出现 validation error 时，优先看 descriptor 与 WGSL 接口；出现间歇性卡顿时，优先看每帧对象创建和 JavaScript 主线程工作量。WebGPU 的核心价值就在于这些对象边界足够清晰，问题可以沿着 device、queue、pipeline、bind group 和 pass 逐层收束。

最小自检任务

你正在实现本章的三角形例子。页面在 HTTPS 环境下运行，navigator.gpu 存在，requestAdapter() 和 requestDevice() 都成功。画布每帧都被清成深色，但三角形没有出现。控制台没有 JavaScript 异常，偶尔出现一条 WebGPU validation message，内容指向 bind group layout 与 shader binding 不兼容。请按 WebGPU device/queue/pipeline 模型写出排查顺序，并指出最可能的三个错误位置。

答案要点

画布能被清屏，说明 context configure、当前 swapchain texture、render pass attachment、command encoder、pass end、command buffer finish 和 queue submit 这条路径至少能执行。排查应从 render pass 内的 draw 相关状态开始；adapter/device 获取路径已由清屏结果提供了基本证据。

第一步检查 WGSL 与 bind group layout。@group(0) @binding(0) var<uniform> uniforms 必须对应 CPU 侧 bindGroupLayout.entries[0].binding === 0，visibility 至少包含 vertex stage，buffer.type 应为 "uniform"，bind group entry 也要绑定同一个编号。validation message 指向 layout 兼容性时，这里是最高概率位置。

第二步检查 pipeline layout 与 bind group。创建 pipeline 时使用的 pipelineLayout 必须包含当前 bind group layout；帧循环中 pass.setBindGroup(0, bindGroup) 的 group index 要与 WGSL 的 @group(0) 对齐。若 pipeline 使用 layout: "auto"，从 pipeline 取得的 layout 与手写 bind group layout 可能存在差异，调试阶段应固定为显式 layout。

第三步检查顶点输入与 draw。setVertexBuffer(0, vertexBuffer)、draw(3)、vertex buffer arrayStride、attribute shaderLocation、offset 和 format 要与 WGSL 的 @location(0)、@location(1) 匹配。若 bind group 错误修复后仍无三角形，再检查 uniform offset 是否把顶点移出 clip space，以及 canvas 尺寸是否为有效像素尺寸。

核心结论是：清屏色可见代表 render pass 输出路径基本有效；binding validation 指向 shader 资源接口合同；三角形缺失应优先收束到 bind group layout、pipeline layout、setBindGroup 和 vertex layout 四个对象边界。

本章知识点总结

• 显式模型：WebGPU 通过 device、queue、pipeline、bind group 和 pass descriptor 把 GPU 工作提前结构化。
• 设备入口：GPUAdapter 表示可用 GPU/驱动组合，GPUDevice 表示页面使用的逻辑设备。
• 队列职责：GPUQueue 接收 command buffer，也提供小块数据上传入口，例如 writeBuffer。
• 管线合同：GPURenderPipeline 固定 shader entry point、顶点布局、primitive state、target format 和资源布局。
• 绑定合同：WGSL 的 @group 与 @binding 需要同时匹配 bind group layout、bind group 和 pipeline layout。
• 帧路径：一帧 WebGPU 绘制通常经历写入本帧数据、获取当前 texture、编码 pass、draw、finish 和 submit。
• 格式一致：context configure 使用的 canvas format 必须与 render pipeline 的 fragment target format 对齐。
• WGSL接口：@location、@builtin(position)、var<uniform> 和 entry point attribute 共同描述 shader 与 host 的接口。
• 对象复用：shader module、pipeline、bind group layout、静态 buffer 和大部分 bind group 应在初始化阶段创建并复用。
• 上传粒度：小块 uniform 更新适合 queue.writeBuffer，大量动态数据需要批量组织和按帧资源管理。
• 错误作用域：pushErrorScope 与 popErrorScope 可以把 validation error 定位到资源创建、pipeline 创建或命令编码阶段。
• 排查顺序：先看运行环境和资源创建，再看 WGSL/descriptor 接口，最后看帧命令和性能症状。