前端工程化 / 系统课时

配置 Worker 与 Web Worker

配置 Worker 与 Web Worker

本课完成一个可运行的模块 Worker,并把它纳入 Vite 的独立 Worker 构建配置。你将明确主线程与 Worker 的入口关系,正确设置专用插件和输出格式,同时验证模块导入、资源 URL 与环境变量在 Worker 中的行为。

学习目标

  • 使用 Vite 推荐的构造器语法创建模块 Worker,并完成主线程消息通信。
  • 配置 worker.plugins、worker.format 和 worker.rolldownOptions。
  • 排查 Worker 在开发正常、生产构建失败时的插件、资源和环境变量问题。

理解 Worker 的独立构建管线

主线程通过 new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' }) 声明 Worker 入口。new URL() 必须直接写在 Worker 构造器中,参数和选项应保持静态字面量,Vite 才能在构建时识别入口并重写资源地址。:contentReference[oaicite:3]{index=3}

Worker 不是主线程模块的普通动态导入。它拥有独立全局作用域、独立模块图和独立输出文件,通过结构化克隆的消息在两个线程间传递数据。Worker 内不能直接访问 DOM,也不能默认使用 Node.js 内置模块。

Vite Worker 独立构建与消息流

配置专用插件与输出行为

当前 Vite 的 worker.plugins 是一个工厂函数,每次应返回新的插件实例,因为多个 Worker 构建可能并行执行。顶层 plugins 在开发阶段可参与 Worker 转换,但生产构建需要把 Worker 专用插件放入 worker.plugins。Vite 8 使用 worker.rolldownOptions 定制底层构建,旧的 worker.rollupOptions 仅作为已弃用别名保留。:contentReference[oaicite:4]{index=4}

下面配置将 Worker 输出为 ES 模块,并用专用插件打印最终生成的 Worker chunk。worker.format 也可设为 iife;模块 Worker 和现代浏览器项目通常选择 es,传统 classic Worker 才考虑 iife。

ts
import { defineConfig, type Plugin } from 'vite'

function workerAuditPlugin(): Plugin {
  return {
    name: 'worker-audit',
    generateBundle(_options, bundle) {
      for (const output of Object.values(bundle)) {
        if (output.type === 'chunk') {
          console.log(`[worker:emit] ${output.fileName}`)
        }
      }
    },
  }
}

export default defineConfig({
  worker: {
    format: 'es',
    plugins: () => [workerAuditPlugin()],
    rolldownOptions: {
      output: {
        entryFileNames: 'assets/worker-[name]-[hash].js',
      },
    },
  },
})

配置生效行为:开发阶段仍按 Vite 的 Worker 转换流程运行;生产构建时会为 Worker 创建新的审计插件实例,并把入口输出到 assets/worker-<NAME>-<HASH>.js。<NAME> 和 <HASH> 由实际入口和内容决定。

编写主线程与 Worker

分别创建 src/hash.worker.ts 和 src/main.ts。Worker 使用浏览器原生 crypto.subtle 计算 SHA-256,主线程只负责发送任务、接收结果和终止线程。

ts
// src/hash.worker.ts
interface HashRequest {
  id: number
  text: string
}

interface HashResponse {
  id: number
  hash: string
  mode: string
}

self.onmessage = async (event: MessageEvent<HashRequest>) => {
  const bytes = new TextEncoder().encode(event.data.text)
  const digest = await crypto.subtle.digest('SHA-256', bytes)
  const hash = Array.from(new Uint8Array(digest), (byte) =>
    byte.toString(16).padStart(2, '0'),
  ).join('')

  const response: HashResponse = {
    id: event.data.id,
    hash,
    mode: import.meta.env.MODE,
  }
  self.postMessage(response)
}

export {}
ts
// src/main.ts
interface HashResponse {
  id: number
  hash: string
  mode: string
}

const worker = new Worker(new URL('./hash.worker.ts', import.meta.url), {
  type: 'module',
})

worker.addEventListener('message', (event: MessageEvent<HashResponse>) => {
  console.log('[worker-result]', JSON.stringify(event.data))
  worker.terminate()
})

worker.addEventListener('error', (event) => {
  console.error('[worker-error]', event.message)
})

worker.postMessage({ id: 1, text: 'vite' })

启动现有 Vite 项目并打开浏览器控制台:

bash
npm run dev

预期结果如下,端口和启动时间可能不同:

text
VITE v<VERSION> ready in <TIME> ms
Local: http://localhost:<PORT>/
[浏览器控制台] [worker-result] {"id":1,"hash":"b16efac145e9242cfb05d739a8509ac7295f381108dce0f753e52a1aaf48e7a1","mode":"development"}

执行生产构建时,审计插件还会输出 Worker 文件名:

bash
npm run build

预期输出包含:

text
[worker:emit] assets/worker-<NAME>-<HASH>.js

处理模块、资源与环境变量

Worker 内可以正常使用 ESM 导入,但依赖必须能在浏览器 Worker 环境运行。若依赖访问 window、document、Node.js 的 fs 或 process,开发阶段可能因路径未触发而暂时正常,生产构建或实际执行时仍会失败。

静态资源应使用可静态分析的导入,或使用 new URL('./file.bin', import.meta.url) 生成资源 URL。不要把完整路径先拼接到变量后再交给 Worker 构造器,因为 Vite 无法可靠识别动态入口。Vite 对 new URL(..., import.meta.url) 的静态资源模式会进行构建期处理,但 URL 字符串需要保持可静态分析。:contentReference[oaicite:5]{index=5}

Worker 中可读取 import.meta.env.MODE、DEV、PROD 和以 VITE_ 开头的公开变量。不要把密钥写入 VITE_ 变量,因为这些值会进入客户端或 Worker 产物;敏感操作应放在服务端接口中。:contentReference[oaicite:6]{index=6}

排查开发与构建差异

开发正常但构建失败时,先确认相关转换插件是否只配置在顶层 plugins,再把 Worker 所需插件以工厂形式加入 worker.plugins。若错误指向输出选项,检查是否仍在使用迁移前的 worker.rollupOptions,并改用 worker.rolldownOptions。

出现模块找不到时,检查 Worker 入口是否使用构造器内联的静态 new URL();资源 404 时,检查是否绕过 Vite 直接拼接了 public 或源码路径;运行时报 window is not defined 时,说明依赖并不兼容 Worker 全局环境。

多 Worker 项目还要避免复用带可变状态的插件实例。把插件创建放在 worker.plugins: () => [...] 内,并让每个实例独立维护缓存、计数器和临时文件,防止并行构建互相污染。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置 Worker 与 Web Worker

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通