使用Storybook与Vitest时Mock模块抛出customEqualityTesters未定义异常

问题场景 #

我基于Vitest搭建了Storybook环境，尝试在Story文件中用Vitest的vi.mock来Mock模块，代码如下：

// my-nice-function.stories.tsx
import { vi } from "vitest";

vi.mock("../some-module", () => ({
  someFunction: vi.fn(),
}));

// 实际的Story代码...

运行Story时抛出错误：

Cannot read properties of undefined (reading 'customEqualityTesters')

栈追踪指向Vitest内部的getCustomEqualityTesters函数，该函数尝试读取globalThis[Symbol.for("$$jest-matchers-object")].customEqualityTesters，但全局对象中不存在这个Symbol对应的条目。

解决方案 #

这个问题是因为Storybook环境没有初始化Vitest依赖的Jest兼容全局匹配器对象，可通过以下步骤修复：

• 创建Vitest初始化文件
  在.storybook目录下新建vitest-setup.ts文件，手动注入缺失的全局对象：

const JEST_MATCHERS_OBJECT = Symbol.for('$$jest-matchers-object');

if (!globalThis[JEST_MATCHERS_OBJECT]) {
  globalThis[JEST_MATCHERS_OBJECT] = {
    customEqualityTesters: [],
    expect: () => ({
      // 按需添加基础方法，避免后续其他匹配器相关错误
      toBe: () => true,
      toEqual: () => true
    })
  };
}

• 在Storybook中引入初始化文件
  修改.storybook/main.ts（或.storybook/main.js），将初始化文件添加到预览配置中：

export default {
  // 其他已有配置...
  previewAnnotations: [
    require.resolve('./vitest-setup.ts'),
  ],
};

• 验证效果
  重启Storybook服务，此时vi.mock即可正常工作，不会再抛出customEqualityTesters相关错误。

如果不需要严格依赖Vitest的Mock API，也可以改用Storybook官方的Mock方案，比如通过Vite的resolve.alias配置来Mock模块。

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