NextJS新项目中ReferenceError: Worker is not defined问题排查与解决

成因 #

Next.js 执行 npm run build 时，会在 Node.js 环境中完成页面预渲染、静态生成等服务端构建流程。而 Worker 是浏览器专属的全局 API，Node.js 运行环境中不存在这个对象。当你在 pages/_app.js 中导入直接导出 Worker 的文件时，这段代码会在服务端构建环节被执行，自然会抛出 ReferenceError: Worker is not defined。

解决方法 #

1. 避免在服务端执行 Worker 相关代码 #

方式一：动态导入并禁用服务端渲染

使用 Next.js 提供的 next/dynamic 工具，指定模块仅在客户端加载：

// pages/_app.js
import dynamic from 'next/dynamic';

const WorkerModule = dynamic(() => import('../myFile.js'), {
  ssr: false // 禁用服务端渲染，确保模块只在浏览器环境加载
});

方式二：添加运行环境判断

修改 myFile.js，仅在浏览器环境导出 Worker：

// myFile.js
module.exports = typeof window !== 'undefined' ? Worker : null;

或者在导入的地方做环境判断：

// pages/_app.js
let workerRef;
if (typeof window !== 'undefined') {
  workerRef = require('../myFile.js');
}

2. Next.js 中使用 Web Worker 的标准姿势 #

如果你的实际需求是在项目中使用 Web Worker，需确保 Worker 的初始化逻辑仅在浏览器环境执行：

Pages Router 场景

在组件的 useEffect 钩子中初始化 Worker（useEffect 仅在浏览器端执行）：

import { useEffect } from 'react';

function MyComponent() {
  useEffect(() => {
    const worker = new Worker('/worker.js');
    // 处理 Worker 消息逻辑
    worker.onmessage = (e) => console.log('Received:', e.data);
    
    // 组件卸载时终止 Worker
    return () => worker.terminate();
  }, []);

  return <div>...</div>;
}

App Router（Next.js 13+）场景

在客户端组件中使用 Worker（添加 'use client' 指令标记为客户端组件）：

// app/components/ClientWorker.js
'use client';

import { useEffect } from 'react';

export default function ClientWorker() {
  useEffect(() => {
    const worker = new Worker(new URL('../worker.js', import.meta.url));
    // 处理逻辑
    return () => worker.terminate();
  }, []);

  return <div>...</div>;
}

内容的提问来源于stack exchange，提问作者user8352734