vite 中 worker.format 用于指定 web worker 打包格式，默认 'iife' 兼容旧环境，'es' 支持现代模块特性但需浏览器支持及 type: 'module' 配合。

在 Vite 中配置 worker.format 是为了控制 Web Worker 脚本的打包输出格式，确保它能在目标环境（尤其是旧版浏览器或特定部署场景）中正确加载和执行。默认值是 'iife'，但根据项目需求切换为 'es' 可以带来更现代、更灵活的模块行为。

worker.format 的作用与取值

worker.format 决定了 Worker 脚本最终被打包成什么模块类型：

• 'iife'（立即执行函数表达式）：

  • 默认格式，兼容性最好，适合不支持原生 ES 模块的环境；
  • 打包后是自包含的函数，无需外部模块系统；
  • 无法直接使用 import 语句（除非配合 importScripts，但受限较多）。

• 'es'（ES Module）：

  • 支持 import / export 语法，可享受 tree-shaking、类型推导、HMR（开发时）等特性；
  • 需搭配 type: 'module' 使用（即 new Worker(..., { type: 'module' })）；
  • 要求运行环境支持 ES 模块 Worker（Chrome 105+、Firefox 111+、Safari 16.4+ 等主流新版浏览器均已支持）。

如何在 vite.config.ts 中配置

在 vite.config.ts 中通过 worker.format 显式设置即可：

Vite

为开发、生产构建和库打包配置并优化 Vite。

下载

import { defineConfig } from 'vite'

export default defineConfig({
  worker: {
    format: 'es' // 或 'iife'
  }
})

✅ 这个配置会影响所有通过 new URL('./xxx.worker.ts', import.meta.url) 或 import Worker from './xxx.worker.ts?worker' 方式引入的 Worker。

配合使用的必要实践

• Worker 实例化必须匹配 format
  若设为 'es'，创建 Worker 时必须传 { type: 'module' }：

  const worker = new Worker(new URL('./calc.worker.ts', import.meta.url), {
    type: 'module' // 必须显式声明
  })

• TS 类型支持需补充声明文件
  在项目根目录或 src 下添加 worker.d.ts，避免 TS 报错：

  declare module '*.worker.ts' {
    const worker: WorkerConstructor
    export default worker
  }

• 注意构建产物路径与部署一致性
  format: 'es' 下，Vite 会把 Worker 打包为 .mjs 后缀（如 assets/calc.xxxxxx.mjs），需确保服务器允许 .mjs MIME 类型（如 application/javascript），否则可能触发 CORS 或 MIME 类型错误。

• 不推荐混用两种加载方式
  不要对同一个 Worker 同时尝试 ?worker 导入和 new URL(...)，尤其当 format 设为 'es' 时，?worker 插件机制已自动适配，而手动 new URL 更可控、更标准。

什么时候该选 es？什么时候选 iife？

• 选 'es'：

  • 项目目标浏览器较新（如仅支持 Chrome ≥105）；
  • Worker 内部大量使用 import 引入工具函数或第三方轻量库（如 lodash-es）；
  • 需要与主线程共享类型定义（如共用 shared-types.ts）；
  • 开发体验优先（HMR 生效、TS 提示完整）。

• 选 'iife'：

  • 需兼容 Safari ≤16.3、旧版 Edge 或企业内网环境；
  • Worker 逻辑极简，无依赖，纯函数式；
  • 部署环境对 .mjs 文件支持不明确（比如某些 CDN 或静态托管平台未配置 MIME）。

不需要额外插件或 polyfill，Vite 原生支持 worker.format，配置后即可生效。