多工作区项目中Cypress/Jest无法识别跨工作区绝对路径别名问题

仓库结构 #

package/
  backend/
    jest.config.cjs
    tsconfig.json
    utils/
  common/
    jest.config.cjs
    tsconfig.json
    utils/
      helpers/
  frontend/
    cypress.config.ts
    tsconfig.json
    utils/

现有配置 #

Backend工作区 #

package.json

"dependencies": {
    "@package-common": "workspace:^",
}

jest.config.cjs

module.exports = {
  ...
  moduleNameMapper: {
    '@utilsCommon/(.*)$': '@package-common/utils/$1',
  },
};

Common工作区 #

jest.config.cjs

module.exports = {
  ...
  moduleNameMapper: {
    '@utilsCommon/(.*)$': '<rootDir>/utils/$1',
  },
};

tsconfig.json

{
  ...
  "compilerOptions": {
    ...
    "baseUrl": "./",
    "paths": {
      "@utilsCommon/*": ["utils/*"]
    }
  },
}

Frontend工作区 #

package.json

"dependencies": {
    "@package-common": "workspace:^",
}

原cypress.config.ts配置

on(
    'file:preprocessor',
    webpack({
      webpackOptions: {
        resolve: {
          ...
          alias: {
            '@utilsCommon': resolve(__dirname, '../common/utils'),
          },
        },

问题 #

在./common/utils/services/http.service.ts里用别名导入函数：

import {
  getUrlApiFhirStaging,
} from '@utilsCommon/helpers';

跑Cypress或Jest测试时，都会提示找不到这个模块。试过把Cypress的别名改成resolve('@package-common/utils')，还是不行。

解决步骤 #

1. 修复Jest配置 #

问题核心是Jest加载Common包内的代码时，无法解析里面的@utilsCommon别名：

• Common工作区自身测试：用tsconfig-paths-jest同步tsconfig的paths配置，避免重复编写moduleNameMapper。先安装依赖：

  npm install tsconfig-paths-jest --save-dev
  

  然后修改common/jest.config.cjs：

  const tsconfig = require('./tsconfig.json');
  const moduleNameMapper = require('tsconfig-paths-jest')(tsconfig);
  
  module.exports = {
    ...
    moduleNameMapper,
  };
  

• Backend/Frontend的Jest配置：直接把@utilsCommon映射到本地的common/utils目录，让Jest加载Common包代码时能正确解析别名：

  // backend/jest.config.cjs
  module.exports = {
    ...
    moduleNameMapper: {
      '@utilsCommon/(.*)$': '<rootDir>/../common/utils/$1',
      '@package-common/(.*)$': '<rootDir>/../common/$1', // 可选，确保@package-common的路径也能正常解析
    },
  };
  

  Frontend的Jest配置（如果有）照此修改即可。

2. 修复Cypress配置 #

Cypress的webpack预处理器需要正确匹配带通配符的别名，并且直接指向文件系统路径：

• 修改frontend/cypress.config.ts的webpack别名：

  const path = require('path');
  
  on('file:preprocessor', webpack({
    webpackOptions: {
      resolve: {
        ...
        alias: {
          // 要匹配带*的路径，对应@utilsCommon/xxx的导入格式
          '@utilsCommon/(.*)': path.resolve(__dirname, '../common/utils/$1'),
        },
      },
    },
  }));
  

• 如果Cypress有单独的cypress/tsconfig.json，也要加上对应的paths配置：

  {
    "compilerOptions": {
      "baseUrl": "./",
      "paths": {
        "@utilsCommon/*": ["../common/utils/*"]
      }
    }
  }
  

3. 额外注意 #

• 保持所有工作区tsconfig的paths别名规则一致；
• 重新执行依赖安装（pnpm install/yarn install），确保workspace包正确链接；
• 给Common包的package.json加上main或exports字段，指向编译后的代码，避免测试工具直接读取源码时出问题。

内容的提问来源于stack exchange，提问作者Julien Diot-Dervaux