paint worklet 必须通过 css.paintworklet.addmodule() 动态加载同源 js 文件注册，不可内联或 script 标签引入；其 paint() 函数接收 paintrenderingcontext2d，仅支持有限绘图 api，且需轻量计算、依赖 css 自定义属性响应式更新，兼容性限 chromium，降级需 @supports 和结构兜底。
Paint Worklet 必须走 addModule 注册，不能内联或 script 标签加载
直接在 HTML 里写 <script>registerPaint(...)</script> 或用 <script src="painter.js"></script> 加载 worklet 文件，完全无效——浏览器不会识别，也不会报错，背景就变成透明。必须用 CSS.paintWorklet.addModule() 动态加载一个独立的 JS 文件，且该文件需满足：同源、MIME 类型为 application/javascript、无 DOM 访问（不能用 document 或 window）。
常见错误现象：background-image: paint(myPattern) 渲染为空白，DevTools 的 Rendering 面板里也看不到绘制痕迹；控制台静默，没有提示。
-
addModule()是异步操作，必须等它 resolve 后再插入相关 CSS，否则样式不生效 - 路径支持相对路径（如
'./painter.js'）、绝对路径、甚至blob:URL，但不支持跨域（除非配好 CORS） - 注册名（
registerPaint('myPattern', ...)中的第一个参数）必须和 CSS 中paint(myPattern)完全一致，大小写敏感，拼错就失效
paint() 函数参数不是 Canvas 2D Context，能用的方法有限
paint(ctx, geometry, properties) 的 ctx 是 PaintRenderingContext2D，不是标准的 CanvasRenderingContext2D。它删减了大量高开销 API，比如没有 save()/restore()、transform()、drawImage()，Chrome 115+ 才开始支持 clip()，且非全平台可用。
你能安全用的绘图方法只有这些：fillRect()、strokeRect()、clearRect()、fillText()、strokeText()、beginPath()、arc()、lineTo()、stroke()、fill()。所有数学计算必须轻量——别在 paint() 里做 for 循环生成上千个点，更别调用 Math.random() 或查 LUT 表。
-
geometry.width和geometry.height是当前元素实际用于绘制背景的尺寸（单位 px），不是clientWidth，也不受box-sizing影响 -
properties.get('--my-prop')只能读取显式声明过的 CSS 自定义属性，且必须提前写进inputProperties数组，否则返回undefined - 如果需要响应式缩放（比如 Retina 屏），别手动算 dpr——
geometry已自动适配设备像素比
响应式更新靠 CSS 自定义属性 + registerProperty，不是 JS 直接改 canvas
想让背景随时间动起来，不能在 paint() 里调用 requestAnimationFrame 或维护状态变量——worklet 线程无事件循环，也不共享内存。正确做法是：主线程用 CSS.registerProperty() 声明可动画的自定义属性（如 --time），再用 element.style.setProperty() 持续更新它；worklet 里只读这个值，做纯函数式计算。
示例场景：正弦波浪背景随时间流动。主线程只需：
CSS.registerProperty({
name: '--wave-time',
syntax: '<number>',
inherits: false,
initialValue: 0
});
// 然后 requestAnimationFrame 里：
element.style.setProperty('--wave-time', Date.now() / 1000);</number>
worklet 里则只做：
paint(ctx, geom, props) {
const t = props.get('--wave-time').value;
// 仅用 t 算 sin(y + t)，不 new 对象、不递归、不 IO
for (let y = 0; y
- 避免在
paint()内做任何耗时操作：字符串拼接、对象创建、浮点密集运算都可能卡住合成线程 - 如需复杂状态（如噪声纹理），用
SharedArrayBuffer+Atomics从 Worker 推数据，主线程只做属性透传 -
registerProperty()是跨线程同步的唯一可靠通道，比 postMessage 更低延迟、更可控
兼容性与降级必须显式处理，不能依赖 feature detect
截至 2026 年 6 月，CSS.paintWorklet 仅在 Chromium 内核浏览器（Chrome ≥ 88、Edge ≥ 88）中稳定支持；Firefox 和 Safari 仍无实现计划。你无法用 if ('paintWorklet' in CSS) 安全判断——即使存在，也可能因策略限制被禁用（如 iframe sandbox 或某些企业策略）。
降级方案不是“加个 fallback background”，而是结构级兜底：用 @supports (background-image: paint(foo)) 包裹高级样式，同时提供纯 CSS 渐变或 SVG 图案作为 fallback；JS 层注册失败时，应主动切换 class 或移除依赖 worklet 的样式规则。
- 不要把
addModule()放在 try/catch 里指望捕获异常——失败时通常静默，得监听moduleLoadError事件（需配合PerformanceObserver或渲染帧检测） - 调试只能靠 DevTools 的 Rendering 面板 → “Paint Worklet” 标签页，console.log 在 worklet 里无效
- 真正复杂的图形（如分形、粒子系统）建议拆成多层：核心结构用 paint()，动态细节用 Canvas + CSS blend-mode 叠加，兼顾性能与表达力
实际落地时最易被忽略的是：paint() 的执行频率和主线程无关，它由浏览器重绘节奏驱动，但每次调用都必须在几毫秒内完成。一旦数学逻辑膨胀，掉帧会直接发生在合成线程，用户感知就是背景“卡顿”，且无法用 performance profile 定位——因为没 JS stack trace。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
