前端工程化 / 系统课时
配置 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.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。
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,主线程只负责发送任务、接收结果和终止线程。
// 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 {}// 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 项目并打开浏览器控制台:
npm run dev预期结果如下,端口和启动时间可能不同:
VITE v<VERSION> ready in <TIME> ms
Local: http://localhost:<PORT>/
[浏览器控制台] [worker-result] {"id":1,"hash":"b16efac145e9242cfb05d739a8509ac7295f381108dce0f753e52a1aaf48e7a1","mode":"development"}执行生产构建时,审计插件还会输出 Worker 文件名:
npm run build预期输出包含:
[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: () => [...] 内,并让每个实例独立维护缓存、计数器和临时文件,防止并行构建互相污染。