Web Worker模块化脚本编写指南

Web Worker 模块化的核心在于使用 ES 模块结合 new URL 实现零配置、可复用的结构，现代构建工具会自动完成打包处理。如果项目需要兼容较旧的环境，Browserify 或 web-worker 库同样可以胜任。无论选择哪种方案，有几个关键点必须注意：避免操作 DOM API、使用相对路径、仅通过 postMessage 进行通信——这些是基本要求。

为 Web Worker 编写模块化脚本，本质上是让 Worker 代码具备可复用、可维护、可测试的结构，同时适应浏览器环境的限制——例如不能直接 import 普通 ES 模块路径、不能访问 DOM。手动拼接脚本已经不是主流做法，现代开发通常采用构建工具或原生 Module Workers，这才是真正的模块化实现方式。

使用 ES 模块 + new URL（推荐，零配置主流方案）

这是目前最便捷的方案，兼容性好，无需额外 loader。Vite、Webpack 5+、Rsbuild、UmiJS 4 等现代构建工具均支持。

• Worker 脚本本身使用 export / import 组织逻辑，例如：

// src/worker/calculator.js
export function multiply(a, b) {
  return a * b;
}

// src/worker/worker.js
import { multiply } from './calculator.js';

self.onmessage = (e) => {
  const { a, b } = e.data;
  self.postMessage({ result: multiply(a, b) });
};

• 主线程中使用 new URL(..., import.meta.url) 创建 Worker：

// src/index.js
const worker = new Worker(new URL('./worker/worker.js', import.meta.url));
worker.postMessage({ a: 10, b: 20 });
worker.onmessage = (e) => console.log(e.data.result); // 200

• 构建工具会自动将 Worker 打包成独立 chunk，模块解析和路径映射全部自动处理
• TypeScript、CSS-in-JS、JSON 导入等也一并支持，具体取决于构建配置

使用 Browserify 打包 Worker 模块（适合 Node.js 风格开发）

如果项目仍沿用 CommonJS，或需要兼容较旧的构建流程，Browserify 依然可靠——尤其适合需要迁移大量 require() 代码的场景。

• Worker 文件保持 Node.js 风格模块写法：

// worker.js
const { processData } = require('./utils');
const { logger } = require('./logger');

self.onmessage = (e) => {
  logger('start processing');
  const result = processData(e.data);
  self.postMessage(result);
};

• 使用 Browserify 打包成单文件：

npx browserify worker.js -o dist/worker.bundle.js

• 主线程加载打包后脚本：new Worker('dist/worker.bundle.js')
• 优势：自动解析 require 依赖，支持 transform（如 babelify、tsify）
• 注意：依赖中绝对不能出现 DOM API 或 window 相关对象

使用 web-worker 库统一跨平台模块 Worker

当项目需要在浏览器和 Node.js 之间切换（例如 SSR 或测试场景），web-worker 提供一致的 Module Workers 接口，帮助屏蔽底层差异。

• 安装：npm install web-worker
• Worker 仍使用标准 ES 模块语法，主线程使用其封装的 Worker 构造函数：

// main.js
import Worker from 'web-worker';
const url = new URL('./worker.js', import.meta.url);
const worker = new Worker(url);

• Node.js 环境下自动 fallback 到 worker_threads，浏览器下走原生 Worker
• 支持 {type: 'module'}，无需额外构建步骤（但需要 Node.js ≥12.8）
• 适合需要统一测试、CI/CD 多环境验证的工程化项目

关键注意事项与避坑点

无论选择哪种方案，以下细节直接影响模块化 Worker 的稳定性：

• 路径必须相对且明确：Worker 内部的 import 或 importScripts 路径不能是绝对 URL（除非同源），也不支持 bare import（例如 import _ from 'lodash'），需要依靠构建工具解析或提前打包
• 禁止访问主线程上下文：模块中不能出现 document、window、localStorage，fetch 在部分浏览器中有限制，XMLHttpRequest 建议改用 fetch
• 通信是唯一桥梁：模块之间无法共享状态，所有数据必须通过 postMessage() 传递。支持结构化克隆（包括 ArrayBuffer、TypedArray），但不支持函数、DOM 节点、循环引用
• 错误需显式捕获：Worker 内部未捕获的异常不会冒泡到主线程，建议在顶层添加 self.onerror = ...，并主动通过 postMessage 发送错误信息