5 个 workly 常见陷阱与限制你必须知道（附完整避坑清单）

workly 是一个体积仅约 1kB 的轻量级 JavaScript 工具库，只需一行 workly.proxy() 就能把独立的函数或类搬进 Web Worker 线程执行，让耗时的 CPU 任务不再卡死界面。对于前端新手来说，它几乎是"把函数丢进 Worker"最简单的方式——但正因为过于简单，它的边界和限制容易被忽视。

本文结合源码（index.js）逐个拆解 5 个最常见的 workly 陷阱，并附上一份完整的避坑清单，帮你在动手前就绕开这些坑。

快速认识 workly：1kB 把函数搬进 Web Worker

在讲陷阱之前，先 30 秒了解 workly 的三个核心 API（实现见 index.js）：

API	作用	使用位置
workly.proxy(fn)	把函数/类序列化后丢进一个新创建的 Worker 中执行	主线程
workly.proxy("worker.js")	连接一个自定义 worker 文件	主线程
workly.expose(obj)	在 Worker 中把函数/对象/类暴露给主线程	Worker 内

它的魔法在于：workly.proxy(函数) 会调用 Function.prototype.toString() 取出函数源码，打包成一个 Blob 临时文件再喂给 Worker（见 index.js#L3-L15）。理解了这一点，下面几乎所有陷阱就都顺理成章了。

官方示例可以参考 examples/function.html（函数版）、examples/class.html（类版）。

陷阱 1：函数依赖外部变量或第三方库，Worker 里静默报错甚至挂起

⚠️ 这是新手踩得最多、也最迷惑人的一个坑。

由于 workly 只搬运函数源码文本本身，函数体内引用的任何外部东西——闭包变量、import 进来的模块、第三方库——都不会被一起带过去。如果函数依赖了 moment 之类的外部库，Worker 内部会直接抛出 ReferenceError。

更坑的是：workly 只监听了 Worker 的 message 事件，没有监听 error 事件（见 index.js#L53-L67）。Worker 脚本加载阶段抛出的错误根本传不回来，你的 await 会永远挂起，既不报错也不返回，排查起来非常痛苦。

正确姿势：用自定义 worker 文件。 把依赖库和函数一起放进 worker.js，在 worker 内部用 importScripts 引入库，再调用 workly.expose() 暴露目标函数。官方的 examples/worker.js 就是一个标准范例——它把 moment.js 和 workly 一起载入 worker，暴露出依赖 moment 的 friendlyTime 函数，主线程则用 workly.proxy("./worker.js") 接入。

另外注意：自定义 worker 里必须调用 workly.expose()，否则 worker 内没有任何消息监听器，主线程的调用同样会无声挂起。

陷阱 2：所有调用都是异步的，首次调用还有额外延迟

workly 中的一切跨线程交互——调用方法、读属性、写属性、实例化类——全部返回 Promise，必须 await：

let a = await new WAdder();   // 实例化也是异步的
console.log(await a.count);   // 读属性也要 await
console.log(await a.add(23, 16));

两个衍生注意点：

• 无法同步使用返回值。 如果你的逻辑要求"调用完立刻拿到结果"，workly 帮不了你，耗时任务必须与同步流程解耦。
• 首次调用明显更慢。 第一次 workly.proxy() 会创建 Worker、解析执行函数源码，之后才有实际执行。若把 proxy 放在热路径里每次现建现调，延迟会远超预期——创建一次、反复复用才是正确用法。

陷阱 3：参数按值传递，函数与 DOM 对象都传不过去

主线程和 Worker 之间走的是 postMessage 结构化克隆（structured clone），这意味着：

• 没有引用语义。 你传一个对象进去，Worker 拿到的是副本。Worker 里怎么修改它，主线程的原对象都毫无变化（官方 Caveats 也明确说明了这一点，见 README.md#L94-L97）。
• 函数、DOM 节点、Symbol 等非可克隆类型不能作为参数传递，会直接失败。
• 传回的也是"数据快照"，类实例只能通过代理对象 await 访问其属性，不能拿到真正的实例做 typeof、instanceof 或引用比较。

一句话：Worker 只适合"吃数据、吐数据"的纯计算，不要指望用它做需要共享可变状态或回调通信的逻辑。examples/worker2.js 演示了普通对象和 Promise 返回值的正确用法。

陷阱 4：Worker 内没有 DOM，界面操作必须回主线程

Web Worker 线程天生没有 document、window，workly 不会也不能为你"变出"一个。如果你的函数里出现了 document.getElementById(...) 之类的操作，搬到 Worker 后必然报错。

正确分工是：Worker 负责算，主线程负责画。 让 Worker 函数返回纯数据（数组、JSON、字符串等），await 拿到结果后再在主线程中更新 DOM。

陷阱 5：错误只剩一行字符串，Worker 资源也不会自动释放

两个容易忽视的生命周期问题：

• 错误堆栈丢失。 Worker 内抛出的异常会被 err.toString() 压成一行字符串传回主线程（见 index.js#L108-L113），完整的 stack 信息没了。调试时若看到 Error: ... 却找不到出处，先想想是不是丢了堆栈。
• Worker 不会自动回收。 workly 没有提供 terminate() 之类的销毁 API，每调用一次 workly.proxy(fn) 就新建一个存活到页面关闭的 Worker。如果在循环或频繁执行的事件处理里反复创建代理，Worker 会越积越多。请把代理对象缓存为单例，整个页面复用同一个。

完整避坑清单：开发前对照一遍 ✅

#	场景 / 陷阱	典型表现	规避建议
1	函数依赖闭包变量、import 模块或第三方库	Worker 内 ReferenceError，await 永久挂起且不报错	改用自定义 worker 文件 + importScripts + workly.expose()，参考 examples/worker3.js
2	把 await 当同步用，或在热路径里反复 proxy	逻辑时序错乱；首次调用明显卡顿	全程 async/await；代理对象创建一次后全局复用
3	期望 Worker 修改主线程对象，或传函数/DOM 作参数	修改"没生效"，传参直接失败	按值思维写代码：传纯数据进去，拿纯数据出来
4	在 Worker 函数里操作 DOM	运行时 document is not defined	Worker 只算数据，主线程 await 后更新界面
5	忽略错误堆栈丢失，频繁创建代理	报错难定位；Worker 泄漏越积越多	关键函数自行返回含错误详情的对象；缓存代理为单例

总结：workly 适合什么、不适合什么

适合：CPU 密集的纯函数（排序、过滤、格式化、加密、大数据量计算）、与外界无依赖的独立类、以及依赖第三方库的函数（走自定义 worker 方案）。它的"一行代码"体验确实是目前把函数搬进 Web Worker 成本最低的方式。

不适合：需要高频细粒度调用（每次跨线程往返都有成本）、依赖共享引用状态、需要回调通信或直接操作 DOM 的逻辑——这类需求应考虑 SharedArrayBuffer、消息协议或成熟的 worker 通信框架。

把握上面的 5 个边界，workly 就能成为一个稳定省心的性能优化小工具。