Next.js项目Jest测试中ReferenceError: TextEncoder未定义的解决方法

针对Next.js+Typescript+React项目、Node.js v16.18.0环境下的这个错误，按以下步骤排查修复：

1. 确保Jest配置文件正确引入setup脚本 #

检查jest.config.js是否配置了setupFilesAfterEnv，确保setup脚本在测试环境初始化后执行。正确的Next.js Jest配置示例：

const nextJest = require('next/jest')
const createJestConfig = nextJest({
  dir: './', // 项目根目录路径
})

const customJestConfig = {
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  testEnvironment: 'jest-environment-jsdom', // 必须指定为jsdom，模拟浏览器环境
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1', // 适配项目中的别名配置，按需调整
  },
}

module.exports = createJestConfig(customJestConfig)

2. 修正jest.setup.js的全局挂载逻辑 #

确保TextEncoder和TextDecoder正确挂载到全局对象，根据项目模块规范选择对应写法：

ES Modules 写法 #

import { TextEncoder, TextDecoder } from 'util';

global.TextEncoder = TextEncoder;
global.TextDecoder = TextDecoder;

CommonJS 写法 #

const { TextEncoder, TextDecoder } = require('util');

global.TextEncoder = TextEncoder;
global.TextDecoder = TextDecoder;

3. 适配isomorphic-dompurify的环境依赖 #

isomorphic-dompurify在Node环境下依赖完整的DOM环境，可在jest.setup.js中补充DOM初始化：

import { JSDOM } from 'jsdom';

const dom = new JSDOM('<!doctype html><html><body></body></html>');
global.window = dom.window;
global.document = dom.window.document;

注：如果已使用jest-environment-jsdom，这一步可能可选，但部分场景下需要显式初始化。

4. 检查jest-config.d.ts类型声明 #

如果该文件存在全局类型覆盖问题，可添加以下声明确保TS识别全局的TextEncoder：

declare global {
  interface Window {
    TextEncoder: typeof TextEncoder;
    TextDecoder: typeof TextDecoder;
  }
}

export {};

若暂时不确定是否影响，可先注释该文件测试，确认问题是否由类型声明导致。

5. 清除Jest缓存 #

缓存可能导致配置未生效，执行以下命令清除缓存后重新运行测试：

npx jest --clearCache

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