Vite ?worker 怎样把 Web Worker 作为模块导入

在 Vite 项目里要把计算放进 Web Worker，最小且清晰的写法是给 Worker 文件加上 ?worker 查询参数：导入结果是一个 Worker 构造器，调用 new 后再通过 postMessage 和 message 事件交换数据。

官方地址：https://vite.dev/guide/features.html#web-workers

这和普通的 import './worker.js' 不同。普通导入会把文件当作应用模块处理；?worker 则告诉 Vite 把它当成 Worker 入口，并在构建时处理对应资源。

?worker 导入到底返回什么

先记住一个判断：import Worker from './worker?worker' 得到的不是已经运行的线程，也不是 Worker 文件里的普通导出，而是可以用 new Worker() 实例化的构造器。

最小配方：文件和页面模块分开

把 Worker 代码放在独立文件中，例如 src/workers/sum.worker.ts。Worker 内部只处理消息并回传结果，页面模块负责创建实例和结束生命周期。

// src/workers/sum.worker.ts
// 只接收两个数字并回传结果，避免把页面状态直接带进 Worker。
self.onmessage = (event: MessageEvent) => {
  const { left, right } = event.data
  // 返回一个带类型的结果，页面侧可以统一处理 message 事件。
  self.postMessage({ value: left + right })
}

// src/main.ts
// ?worker 导入的是 Worker 构造器，不是已经启动的实例。
import SumWorker from './workers/sum.worker?worker'

const worker = new SumWorker()

// 先注册接收处理器，再发送消息，避免过早发送导致调试顺序混乱。
worker.addEventListener('message', (event: MessageEvent) => {
  console.log('计算结果：', event.data.value)
})

// 发送可结构化克隆的数据，不要直接传递 DOM 节点或函数。
worker.postMessage({ left: 12, right: 30 })

// 页面不再使用时释放线程资源，单页应用切换页面时尤其重要。
window.addEventListener('beforeunload', () => worker.terminate(), { once: true })

这里的 new SumWorker() 才是创建 Worker 的位置。若把 SumWorker 当作普通函数调用，或者误以为导入本身已经启动线程，通常会得到构造方式错误或生命周期失控的问题。

关键 JavaScript：先约定消息协议

Worker 的价值不只是“换一个文件”，而是把主线程和后台线程之间的数据边界固定下来。建议先定义动作和结果字段，再扩展计算逻辑。

// src/workers/thumbnail.worker.ts
// 用动作字段区分消息类型，后续扩展 resize、decode 等任务时更容易维护。
type WorkerRequest = {
  action: 'sum'
  values: number[]
}

type WorkerResponse =
  | { ok: true; value: number }
  | { ok: false; message: string }

self.onmessage = (event: MessageEvent) => {
  const request = event.data

  // 在 Worker 边界检查输入，避免 NaN 或空数组悄悄进入业务结果。
  if (request.action !== 'sum' || request.values.length === 0) {
    const response: WorkerResponse = { ok: false, message: 'values 不能为空' }
    self.postMessage(response)
    return
  }

  const value = request.values.reduce((total, current) => total + current, 0)
  const response: WorkerResponse = { ok: true, value }
  self.postMessage(response)
}

涉及大型 ArrayBuffer 时还可以使用 transferable objects，减少复制成本；但这会转移主线程对缓冲区的所有权，发送前要明确后续代码不会继续读取原对象。

默认 Worker、inline 和 shared worker 怎么选

Vite 官方功能文档列出几种相关查询参数。它们解决的问题不同，不能只按“代码能不能跑”来选择：

默认先从 ?worker 开始，只有在明确需要内联或跨上下文共享时再切换。这样更容易观察资源边界，也不会让构建产物策略和通信模型同时发生变化。

TypeScript 为什么提示找不到 ?worker 类型

Vite 提供了 vite/client 类型声明，里面包含资源导入以及部分 Vite 注入能力的类型提示。项目使用 TypeScript 时，可以在 tsconfig.json 中加入：

// tsconfig.json
{
  "compilerOptions": {
    "types": ["vite/client"]
  }
}

如果项目已经指定了 compilerOptions.types，数组会限制可见的全局类型包，所以要把 vite/client 和现有类型一起保留。也可以在环境声明文件中使用三斜线引用：

/// 
// 该声明让 TypeScript 认识 Vite 的资源查询参数和客户端类型。

Vite 负责转译 TypeScript，但不会在转译阶段完成完整类型检查。生产构建仍应把 tsc --noEmit 作为独立检查，避免把类型错误误认为是 Worker 导入机制的问题。

常见误区与排查顺序

1. 把 ?worker 当作普通模块。先看导入语句是否包含查询参数，再确认调用处是否使用了 new。
2. 只监听 message，不处理 error。生产代码可以同时注册 error 事件，并在失败时结束或重建实例。
3. 把 DOM 节点传给 postMessage。消息使用结构化克隆，函数、节点和带特殊所有权的对象不能按普通对象处理。
4. 忘记 terminate。临时页面、弹窗和组件卸载时应释放 Worker，避免旧实例继续响应消息。
5. 没有先区分 shared worker。如果需求是多个页面共享连接或缓存，应该围绕端口和连接生命周期设计，不要把普通 Worker 硬改成共享模型。

一段完整的使用清单

可以按下面的顺序整理项目：

• Worker 文件只负责后台任务和明确的消息协议。
• 页面模块通过 ?worker 得到构造器，再创建实例。
• 先注册 message、error 处理，再发送可结构化克隆的数据。
• 默认使用独立 Worker 资源，需要内联或共享时分别评估体积和连接模型。
• 在 TypeScript 配置中保留 vite/client，并用独立的 tsc --noEmit 做类型检查。

一句话总结：Vite 的 ?worker 是模块导入层面的构建约定，导入结果是 Worker 构造器；真正的线程生命周期、消息协议和资源释放，仍然需要由应用代码清楚地管理。

相关问题

Vite 的 ?worker 会自动启动线程吗？

不会。导入得到的是构造器，调用 new 后才创建 Worker 实例。

?worker&inline 一定比独立 Worker 文件更好吗？

不一定。内联能减少独立资源，但会增加主产物或启动数据的体积，应按部署和缓存策略选择。

什么时候应该使用 ?sharedworker？

当多个页面或上下文需要共享一个 Worker 及其状态时再考虑它，并同步设计端口连接、广播和断开处理。