WebTransport datagrams 必须显式 releaseLock() 否则后续 getWriter() 会 pending；单次 write 超 maxDatagramSize（通常 1200–1400 字节）将静默丢弃；requireUnreliable: true 是启用 datagram 的硬性开关，非可选配置。
datagrams.writable.getWriter() 必须显式 releaseLock()，否则写入会卡住
调用 transport.datagrams.writable.getWriter() 后拿到的 writer 是一个独占资源，不释放锁就无法再次获取新 writer——这不是警告，是浏览器实际行为。常见现象是：第一次发包成功，第二次 getWriter() 一直 pending，控制台无报错，但数据彻底发不出。
正确做法是每次写完立刻 releaseLock()，哪怕只发一次：
const encoder = new TextEncoder();
const data = encoder.encode("ping");
const writer = transport.datagrams.writable.getWriter();
await writer.write(data);
writer.releaseLock(); // ✅ 必须加这一行
- 别在
finally块里放releaseLock()—— 如果write()抛异常（比如连接已断），writer可能已失效，调用会报"Writer is not writable" - 不要复用同一个
writer多次write()——datagrams.writable不支持连续写入，每次都要新getWriter() - 高频发送时（如游戏状态每帧同步），建议用
try...catch包裹整个流程，避免单次失败阻塞后续
datagram 大小超限会静默失败，不是截断而是丢弃
transport.datagrams.writable 对单次 write() 的数据长度有硬限制：必须 ≤ 当前连接的 maxDatagramSize（通常为 1200–1400 字节）。超出部分不会被自动分片或截断，而是整包被丢弃，且不抛异常、不触发 catch，连 console.error 都没有。
安全做法是发送前主动检查：
立即学习“前端免费学习笔记（深入）”；
const max = transport.datagrams.maxDatagramSize || 1200;
if (data.byteLength > max) {
console.warn(`Datagram too large: ${data.byteLength} > ${max}`);
return; // 或手动分片（需应用层处理）
}
const writer = transport.datagrams.writable.getWriter();
await writer.write(data);
writer.releaseLock();
-
transport.datagrams.maxDatagramSize是只读属性，连接建立后即固定，不可配置 - 服务端也必须适配该大小，QUIC 层不负责跨 datagram 重组，分片逻辑全在应用层
- 别依赖
typeof Blob === "object"这类判断来规避——Uint8Array、ArrayBuffer、string都可能超限
接收端用 readable.getReader() 时，read() 返回 { value, done }，value 可能为 null
transport.datagrams.readable.getReader() 返回的 reader 在调用 read() 时，即使连接正常，value 也可能为 null（例如缓冲区空、瞬时无数据）。直接解构 { value } 并调用 value.length 会报 "Cannot read property 'length' of null"。
标准循环接收模式应为：
async function readDatagrams(reader) {
while (true) {
const { value, done } = await reader.read();
if (done) break;
if (value === null) continue; // ✅ 显式跳过 null
console.log("Received:", new TextDecoder().decode(value));
}
}
const reader = transport.datagrams.readable.getReader();
readDatagrams(reader);
- 不要用
for await (const chunk of reader)——ReadableStreamDefaultReader不支持 async iterable 协议 -
reader.closed是 Promise，但 resolve 时机不明确；更可靠的是监听transport.closed事件做清理 - 如果接收逻辑复杂（如需解析二进制协议头），建议把
value转成new Uint8Array(value)再操作，避免 DataView 异常
requireUnreliable: true 不是可选配置，是连接能否走 datagram 的开关
创建 WebTransport 实例时，若服务器不支持 HTTP/3 或 QUIC datagram 扩展，即使写了 requireUnreliable: true，连接也会直接失败（transport.ready reject），错误信息类似 "Failed to connect: no datagram support"。这不是兼容性降级逻辑，而是强制校验。
生产环境必须做 fallback 处理：
const transport = new WebTransport('https://api.example.com/wt', {
requireUnreliable: true // ❌ 不加这行，transport.datagrams 可能为 undefined
});
try {
await transport.ready;
} catch (err) {
console.error("Datagram connection failed:", err);
// ✅ 此处降级到 createBidirectionalStream() 或 WebSocket
fallbackToReliableChannel();
}
-
requireUnreliable: true是硬性要求，不是“建议”；不加它，某些浏览器（如 Chrome 125+）会默认禁用 datagram 接口 - 服务端必须明确开启 QUIC datagram 支持（如使用
webtransport-rs需启用datagramfeature） - 别在
transport.datagrams上做存在性判断（如if (transport.datagrams)）—— 它永远存在，但内部可能不可用；真正要看的是transport.ready是否 resolve
