Docusaurus项目中Jest无法找到@theme/Layout模块如何解决？

问题根源 #

你之前的配置失效核心有两个原因：

1. Docusaurus的@theme别名是构建阶段动态生成的，并非固定指向静态路径，旧文档中docusaurus-theme包名已经过时，当前v2/v3版本默认使用的经典主题包为@docusaurus/theme-classic
2. Jest的moduleDirectories配置无法直接处理带前缀的别名路径，需要配合别名映射规则才能生效

解决方案 #

方案一：Mock Docusaurus 主题模块（单元测试优先推荐）

单元测试只需要验证你自身的业务逻辑，不需要加载真实的Docusaurus主题组件，直接Mock所有Docusaurus相关模块即可，成本最低且不会引入额外依赖问题。

1. 修改jest.config.js，添加别名映射规则：

module.exports = {
  // 保留你原来的其他配置
  moduleNameMapper: {
    // 映射@theme前缀到mock目录
    '@theme/(.*)': '<rootDir>/src/__mocks__/@theme/$1.js',
    // 映射@docusaurus前缀到mock目录
    '@docusaurus/(.*)': '<rootDir>/src/__mocks__/@docusaurus/$1.js',
    // 样式文件mock，需要先安装identity-obj-proxy依赖
    '\\.(module\\.)?(css|scss|sass)$': 'identity-obj-proxy'
  }
}

2. 新建mock文件目录和对应组件：

• 新建src/__mocks__/@theme/Layout.js：

import React from 'react';
// 直接返回一个透传children的简单组件即可
export default function Layout({ children, ...props }) {
  return <div data-testid="docusaurus-layout" {...props}>{children}</div>;
}

• 新建src/__mocks__/@docusaurus/useDocusaurusContext.js，根据你业务中用到的返回字段自定义内容：

export default function useDocusaurusContext() {
  return {
    siteConfig: {
      title: '测试站点',
      // 你业务中用到的其他配置字段都可以在这里定义
    }
  };
}

方案二：加载真实主题组件（集成测试用）

如果你的测试场景必须用到真实的Layout组件，可以配置正确的主题路径：

1. 修改jest.config.js：

module.exports = {
  // 保留你原来的其他配置
  moduleNameMapper: {
    // 先去掉@theme别名前缀
    '@theme/(.*)': '$1',
    '\\.(module\\.)?(css|scss|sass)$': 'identity-obj-proxy'
  },
  moduleDirectories: [
    'node_modules',
    // 优先加载用户swizzle的自定义主题组件
    'src/theme',
    // 再加载官方经典主题的组件，路径要对应你安装的主题包路径
    'node_modules/@docusaurus/theme-classic/src/theme'
  ]
}

注意：真实主题组件会依赖大量Docusaurus运行时模块，你仍然需要Mock所有用到的运行时依赖，否则还是会报模块找不到的错误。

排查步骤 #

如果配置后仍然报错，可以按以下步骤排查：

• 执行包管理命令确认你使用的主题包实际安装路径：
  npm用户执行npm ls @docusaurus/theme-classic
  yarn用户执行yarn list @docusaurus/theme-classic
  pnpm用户执行pnpm list @docusaurus/theme-classic
• 如果你自定义了其他主题包，把配置里的经典主题路径替换为你实际使用的主题包路径即可
• 如果你有swizzle过Layout组件存放在src/theme/Layout.js，Jest会优先加载该文件，符合Docusaurus的主题覆写逻辑

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