别把耗时任务全喂给主线程：HarmonyOS Worker 线程完全拆解

做 ArkUI 开发的朋友多半有过这种经历：一个图像处理、大文件解析或者超长循环计算一跑，UI 直接卡死，手指按下去连涟漪动画都凝住了，用户只看到死寂的屏幕。

这不是 ArkTS 慢，而是你的耗时逻辑跑在了 UI 线程上。HarmonyOS 的并发模型是 Actor 式隔离——线程间不共享可变状态，靠消息传递通信——而 Worker 就是系统给你开的那个"合法后台线程大门"。但它不是银弹，用好了香，用不好就是内存泄漏和一堆 postMessage 序列化地狱。

今天从头到尾拆清楚：Worker 到底是什么模型、消息是怎么序列化过去的、最小可运行项目怎么搭、常见坑位（以及为什么你的 AppStorage 在 Worker 里永远是 undefined）、什么时候该选 Worker 而不是 TaskPool，最后瞄一眼 HarmonyOS 6 / API 22 可能变化的边界。

---

一、核心直觉：Worker 不是"新开个线程跑函数"，而是"开个子进程式的隔离世界"

传统多线程思维是 共享内存 + 锁（pthread / std::thread 那种），但 ArkTS 的 Worker 走的是 内存隔离 + 结构化克隆（Structured Clone）：

• 主线程（宿主线程） 和 Worker 线程 各自有一套独立的 ArkTS 运行时实例、独立全局对象、独立堆。
• 它们之间不共享对象引用。你把一个 { foo: someObject } 交给 Worker，对方拿到的是深拷贝出来的快照（或特定条件下的所有权转移，比如 ArrayBuffer 走 transfer）。
• Worker 不能也不准碰 UI——没有 builder()、没有 AppStorage、没有 router、没有 @State。它的整个世界就是纯数据和计算。

一句话定性：Worker 更像 fork 了一个极简 JS VM，然后把一个 .ets 文件塞进去跑；两边的纽带只有一条 postMessage 通道。

---

二、一次 postMessage 背后的全程链路

关键细节：序列化那一步决定了你能传什么、不能传什么。函数？不行。带循环引用的对象？不行。ArrayBuffer？可以（拷贝或 transfer）。@Sendable 对象？API 12+ 可以走 postMessageWithSharedSendable 做共享内存语义，但那是另一条路。

---

三、最小可运行闭环：从零搭一个 Worker（不省略配置）

3.1 先在 build-profile.json5 里"登记" Worker 文件

这是最多人踩的坑——你不登记，运行时直接加载失败。

// entry/build-profile.json5（或你的模块级 build-profile）
{
  "buildOption": {
    "sourceOptions": {
      "workers": [
        "./src/main/ets/workers/CalcWorker.ets"
      ]
    }
  }
}

3.2 Worker 线程文件：CalcWorker.ets

Worker 文件必须放 ets/workers/ 目录（约定），它有自己的小世界：

// entry/src/main/ets/workers/CalcWorker.ets
import { worker, ThreadWorkerGlobalScope, MessageEvents, ErrorEvent } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

// Worker 线程的入口逻辑：绑定消息处理器
// 这里没有 @Entry @Component，不是 UI，只是一个执行上下文
workerPort.onmessage = (e: MessageEvents): void => {
  const data = e.data;

  switch (data.cmd) {
    case 'SUM_RANGE':
      // 故意写成“很重的同步循环”——这不会影响主线程
      const start = data.start ?? 1;
      const end   = data.end   ?? 1_000_000;
      let sum = 0;
      for (let i = start; i <= end; i++) {
        sum += i;
      }
      workerPort.postMessage({ cmd: 'SUM_RESULT', result: sum, reqId: data.reqId });
      break;

    case 'SHUTDOWN':
      // 自我了断（优雅）
      workerPort.close();
      break;

    default:
      workerPort.postMessage({ cmd: 'ERROR', msg: `Unknown cmd: ${data.cmd}`, reqId: data.reqId });
  }
};

// 可选的：全局错误处理（比 onerror 更推荐的走法见后文 API 18+）
workerPort.onmessageerror = (ev: MessageEvents) => {
  console.error('[CalcWorker] onmessageerror', ev);
};

3.3 宿主线程（UI 侧）调用它

// pages/Index.ets
import { worker } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  @State status: string = 'Idle';
  private wk: worker.ThreadWorker | null = null;

  aboutToAppear(): void {
    this.initWorker();
  }

  initWorker(): void {
    // 1. 构造 Worker —— 路径格式: '{moduleName}/ets/workers/FileName.ets'
    this.wk = new worker.ThreadWorker('entry/ets/workers/CalcWorker.ets', {
      name: 'CalcWorker' // 可选：线程名，便于 Heap/Perf 工具辨认
    });

    // 2. 收消息
    this.wk.onmessage = (e: worker.MessageEvents): void => {
      const d = e.data;
      if (d.cmd === 'SUM_RESULT') {
        this.status = `结果 = ${d.result}`;
      } else if (d.cmd === 'ERROR') {
        this.status = `${d.msg}`;
      }
    };

    // 3. 错误监听（严肃代码绝不能省）
    this.wk.onerror = (err: Event): void => {
      const e = err as ErrorEvent;
      console.error(`[Worker] onerror: ${e.message ?? err.type}`, e);
      this.status = 'Worker 异常';
    };

    // 4. API 18+ 可用 onAllErrors（覆盖更广的异常生命周期）
    if ('onAllErrors' in this.wk) {
      (this.wk as any).onAllErrors?.((er: any) => {
        console.error('[Worker][AllErrors]', er?.message ?? er);
      });
    }
  }

  startHeavyTask(): void {
    if (!this.wk) return;
    this.status = '计算中…';
    // 发任务（cmd 是我们自己的协议字段；reqId 用来匹配异步回调）
    this.wk.postMessage({
      cmd: 'SUM_RANGE',
      start: 1,
      end: 10_000_000,
      reqId: Date.now()
    });
  }

  stopWorker(): void {
    // 两种方式：主线程强杀 vs 发命令让 worker 自己 close()
    this.wk?.terminate(); // 立即终止（偏硬）
    // 或：this.wk?.postMessage({ cmd: 'SHUTDOWN' });
    this.wk = null;
  }

  aboutToDisappear(): void {
    this.stopWorker();
  }

  build() {
    Column({ space: 20 }) {
      Text(this.status).fontSize(18).margin(30)
      Button('跑一个重计算（后台线程）').onClick(() => this.startHeavyTask())
      Button('终止 Worker').color(Color.Red).onClick(() => this.stopWorker())
    }
    .width('100%').height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

跑起来你会看到：UI 上的按钮动画依然顺滑、页面不卡，因为那个千万级循环在另一个运行时里自顾自地跑。

---

四、序列化规则：什么传得过去、什么会悄悄消失

Worker 的 postMessage 底层是 Structured Clone Algorithm 的一个子集，记住这组"能/不能"就够用了：

传得过去	传不过去（会抛/静默丢弃）
number / string / boolean / null / undefined	函数 / lambda（序列化遇到函数直接 FAIL）
Array / Object（无循环引用）	类实例（丢了 prototype，到对岸只剩 { } 平面数据）
ArrayBuffer / TypedArray（拷贝或 transfer）	UI 组件 / PixelMap / ImageBitmap（需走专门 API）
Date / RegExp（有限支持）	@State 装饰的响应式状态、闭osures 捕获的外部变量
@Sendable 对象（走 postMessageWithSharedSendable）	AppStorage / PersistentStorage / router

实操中最痛的两个教训：

教训 1：别想传"方法"过去

//永远别这么做
worker.postMessage({ callback: () => {} });
// Structured Clone：函数不可序列化 → 要么抛异常要么你收到残缺对象

教训 2：Worker 里没有 AppStorage，也没有 @State

// Worker.ets
const theme = AppStorage.get('theme'); // undefined，而且压根不该在这出现

正确模型：所有 UI 状态留在主线程，Worker 只负责纯数据进出。Worker 做完之后，主线程 onmessage 里更新 @State 一把完事。

---

五、Worker vs TaskPool：不是二选一的宗教，是"任务形状"决定

官方给的选型口诀其实挺准，但我想翻译成更接地气的版本：

维度	TaskPool	Worker
任务时长	短～中等（同步 ≤3min 隐式约束）	长时 / 常驻（>3min、后台一直跑）
生命周期	系统池化，你不管销毁	你手动管 terminate() / close()
并发上限	系统决定（≈CPU核-1）	你决定，但硬上限 64 个
调用形态	taskpool.execute(fn, ...args) 像调异步函数	自己定义 cmd 协议 + 双向 postMessage
典型场景	图像预处理的独立步骤、单次解压、短时密集循环	长时间数据同步、流式解压、持续监听式计算、需要自定义长生命周期

经验法则：

• 如果一个任务是单次、无状态、输入输出清晰 → taskpool.execute 更省力
• 如果要常驻、跑多轮、需要自定义调度/内部状态机 → Worker
• 如果任务量巨大且你发现自己在疯狂 new ThreadWorker() 再 terminate() → 停下来，考虑复用单 Worker + 命令协议（上面例子的 cmd 模式就是）

---

六、小小案例大比对

案例 A：路径写错（最常见）

// 少了模块前缀 / 多写了 src/main 等
new worker.ThreadWorker('./workers/CalcWorker.ets');
// 正确（Stage模型 entry 模块）：
new worker.ThreadWorker('entry/ets/workers/CalcWorker.ets');

同时在 build-profile.json5 的 workers 数组里必须登记，少一步都白搭。

案例 B：忘记 terminate → 内存只涨不跌

Worker 一旦创建，不主动关就不会死。列表页每进一次 pushUrl 就 new ThreadWorker() 一次，几次之后内存曲线像楼梯一样上去。

正确姿势要么：

• 在页面 aboutToDisappear / onPageHide 里调 .terminate()，
• 要么做成全局单例 Worker（整个 App 生命周期只建一个），通过 reqId 区分回执。

案例 C：ArrayBuffer 传一次就没了（transfer 语义）

const buf = new ArrayBuffer(1024);
worker.postMessage({ buf }, [buf]); // ← 第三个参数或 options.transfer
// 这里 buf 在宿主线程已经 "被剥夺所有权" → byteLength = 0

如果你还需要主线程继续用那份数据，就别放 transfer，让它走拷贝；或者改用 @Sendable + postMessageWithSharedSendable（API 12+）走共享内存语义。

---

七、HarmonyOS 6（API 22）适配

Worker 的基础模型（Actor 隔离 + postMessage）是平台级承诺，不会因为 API 22 就推翻。但有几个变化趋势你要提前在代码里留"抗震缝"：

1. 路径与模块解析可能更严格

API 22 对 build-profile.json5 的校验大概率更硬（比如不允许未登记路径静默 fallback）。
适配对策：坚持走登记过的完整路径格式 entry/ets/workers/XXX.ets，别依赖相对路径的灰色行为。

2. priority

ThreadWorkerOptions.priority 枚举（HIGH / MEDIUM / LOW / IDLE / DEADLINE / VIP）在后续版本里可能被系统 QoS 层更严肃地尊重（尤其多 Worker 竞争资源时）。
适配对策：给 Worker 显式设 name + 有意义的 priority，别全挤默认 MEDIUM——将来排查 Heap/Perf 时也更容易区分线程。

new worker.ThreadWorker('entry/ets/workers/CalcWorker.ets', {
  name: 'HeavyMath',
  priority: worker.ThreadWorkerPriority.LOW // 数据同步类后台任务
})

3. onAllErrors

旧写法靠 onerror，但 API 18+ 的 onAllErrors 覆盖更广的生命周期错误（线程不死在 onmessage 里的同步异常也能兜到），且不会导致 Worker 线程立即进入销毁流程（对比旧 onerror 某些路径会）。
适配对策：从现在开始就写两套：

if ('onAllErrors' in wk) {
  wk.onAllErrors = (er) => { /* 不自动杀Worker，你可决定策略 */ };
} else {
  wk.onerror = (err) => { /* 旧版兜底 */ };
}

4. Sendable / 共享对象方向（长期）

@Sendable + postMessageWithSharedSendable 的出现说明系统在未来希望提供比拷贝更高效的跨线程数据通路，而不是让你把所有东西塞 postMessage 然后祈祷 ≤16MB。API 22 时代这条线可能会补齐更多类型支持，但结构化克隆仍然是最稳的通用底座——别提前把所有数据结构改成 Sendable 只为"看起来高级"。

---

八、总结一下下

1. 把它当"数据进 → 计算 → 数据出"的纯管道，UI 状态一滴都别往里塞。
2. 生命周期纪律：谁创建谁销毁；页面退出前清 Worker；长期存活的 Worker 做成单例、用命令协议复用。
3. 消息协议化：别裸传 { data: xxx }，给一个 cmd 字段（就像上面 'SUM_RANGE' / 'SHUTDOWN'），你的 onmessage 永远走 switch(cmd)，三个月后看代码才不会疯。

Worker 不复杂，但它惩罚粗心的方式很直接——卡帧、内存爬坡、或那种"只在真机 QA 手上一小时后炸"的玄学崩溃。把路径登记、terminate、序列化规则三件事钉牢，它就从隐患变成你性能工具箱里最可靠的那个扳手。