Paint Worklet 必须作为独立JS文件通过CSS.paintWorklet.addModule()异步注册，不可内联；渐变需手动创建CanvasGradient并用addColorStop()设色标；动态配置依赖CSS自定义属性；不支持浏览器需显式提供CSS渐变fallback。
Paint Worklet 不能直接写在 HTML 或内联 script 里
浏览器会静默忽略，background: paint(myGradient) 会变成透明或 fallback 色，控制台也不报错——这是最隐蔽的失败方式。根本原因：Paint Worklet 必须作为独立 JS 文件加载，且需通过 CSS.paintWorklet.addModule() 注册，这个过程是异步的，也不能跨域（必须同源或带 Access-Control-Allow-Origin 头）。
常见错误包括：
- 把
registerPaint写在<script>标签里，哪怕加了type="module"也无效 - 用
fetch + eval动态执行 worklet 代码，浏览器直接拒绝 - 路径写错导致
addModule()拒绝加载，比如漏掉.js后缀或用了相对路径但当前页面 URL 有 hash
渐变类 worklet 必须手动创建 CanvasGradient 对象
Paint Worklet 的 paint() 方法里没有 linear-gradient() 这种 CSS 函数可用，所有渐变都得靠 ctx.createLinearGradient() 或 ctx.createRadialGradient() 手动构造，再调用 addColorStop() 设置色标——这点和 <canvas> 完全一致，但上下文对象是 PaintRenderingContext2D，只支持子集 API（比如不支持 setTransform()）。
关键细节：
立即学习“前端免费学习笔记（深入）”；
-
createLinearGradient(x0, y0, x1, y1)的坐标系以画布左上角为原点，x1 - x0和y1 - y0决定方向，不是 CSS 的to right那套语法 - 如果想响应容器宽高变化，要用
size.width和size.height（传入paint()的第二个参数），别硬编码像素值 - 没调
addColorStop()就赋给fillStyle，结果是透明——worklet 不会报错，只会渲染空白
CSS 自定义属性传参是唯一可控的动态方式
想让渐变颜色、角度、位置可配置，不能靠 JS 操作 DOM 或改 style，必须走 CSS 自定义属性（--grad-color-1、--grad-angle 等），并在 worklet 的 inputProperties 静态 getter 中声明。浏览器只监听这些属性变化，触发重绘。
注意兼容性与限制：
-
inputProperties返回的数组只能是字符串，且必须是合法 CSS 属性名（含--前缀），get('--grad-angle').value取出来是原始值（如"45deg"或0.785），需自行解析 - Firefox 和 Safari 当前（2026 年中）仍不支持 Paint Worklet，Chrome/Edge ≥ 88 可用，生产环境必须降级到 CSS 渐变 fallback
- 自定义属性值若为空或非法（如
--grad-color-1: invalid;），properties.get()返回undefined，容易引发Cannot read property 'value' of undefined
fallback 渐变必须显式写在 CSS 里，不能靠 worklet 自动兜底
当 Paint Worklet 加载失败、不支持或 JS 报错时，background: paint(myGradient) 会直接失效，变成透明背景——浏览器不会自动回退到任何 CSS 渐变。你必须手动叠加标准 CSS 渐变：
.element {
background: linear-gradient(135deg, #3b82f6, #8b5cf6);
background: paint(myGradient);
}
这种写法依赖 CSS 层叠规则：后声明的 background 会覆盖前一个，但仅当 paint() 有效时才生效；一旦失效，就自然回退到上一行。别指望 @supports (background: paint()) —— 它目前无法可靠检测 Paint Worklet 是否真正可用（尤其在模块加载失败时）。
最容易被忽略的一点：worklet 是绘制逻辑，不是样式开关。它不改变元素结构、不触发重排，但一旦出错，视觉上就是“突然消失”，排查时得先确认 addModule() 是否 resolve，再查控制台是否有 Uncaught ReferenceError 或 CORS 错误，而不是盯着 HTML 结构找问题。
