Vite Monorepo中@别名跨工作区解析错误的解决方法咨询

核心问题根源 #

Vite的全局别名规则会覆盖依赖包的别名配置，当foo-shared作为子包被foo-bar引入时，Vite会直接使用foo-bar的@别名映射，把foo-shared里的@/quux解析到foo-bar/src/quux，而非foo-shared/src/quux。vite-tsconfig-paths插件仅读取当前项目的tsconfig，不会递归处理工作区依赖包的路径配置，所以无法解决这个问题。

解决方案：动态别名解析 #

通过自定义Vite的别名解析逻辑，根据导入模块的实际所在包目录，动态匹配对应包的@别名指向。

1. 统一管理包路径 #

在项目根目录创建packages.config.js，集中维护所有工作区包的路径映射：

module.exports = {
  'foo-bar': './packages/foo-bar',
  'foo-shared': './packages/foo-shared'
};

2. 修改Vite配置实现动态解析 #

在foo-bar的vite.config.ts中，替换原有的静态别名配置，使用函数式别名来处理：

import { defineConfig } from 'vite';
import path from 'path';
import pkgPaths from '../../packages.config.js';

export default defineConfig({
  resolve: {
    alias: [
      // 主包自身的@别名
      { find: '@', replacement: path.resolve(__dirname, 'src') },
      // 动态处理子包的@别名
      {
        find: /^@\/(.+)$/,
        replacement: (match: string, filePath: string) => {
          // 获取当前导入语句所在文件的路径
          const importerUrl = (import.meta as any).url;
          // 匹配该文件所属的工作区包
          const currentPkg = Object.keys(pkgPaths).find(pkgName => 
            importerUrl.includes(pkgPaths[pkgName].replace('./', ''))
          );

          // 如果是foo-shared包的文件，映射到它的src目录
          if (currentPkg === 'foo-shared') {
            return path.resolve(__dirname, '../foo-shared/src', filePath);
          }
          // 默认使用主包的src目录
          return path.resolve(__dirname, 'src', filePath);
        }
      },
      // 包名别名保持原有配置
      { find: '@foo/shared', replacement: path.resolve(__dirname, '../foo-shared/src') }
    ]
  }
});

3. 确保各包tsconfig配置正确 #

每个包的tsconfig.json中，paths必须正确指向自身的src目录，保证IDE识别正常：

foo-shared/tsconfig.json：

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

foo-bar/tsconfig.json：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@foo/shared/*": ["../foo-shared/src/*"]
    }
  }
}

批量包优化（可选） #

如果工作区包数量较多，可封装工具函数批量生成动态别名规则，减少重复代码：

function createDynamicAlias(pkgName: string, pkgRelativeDir: string) {
  return {
    find: /^@\/(.+)$/,
    replacement: (match: string, filePath: string) => {
      const importerUrl = (import.meta as any).url;
      if (importerUrl.includes(pkgRelativeDir.replace('./', ''))) {
        return path.resolve(__dirname, pkgRelativeDir, 'src', filePath);
      }
      return path.resolve(__dirname, 'src', filePath);
    }
  };
}

// 在vite.config的alias数组中使用
alias: [
  { find: '@', replacement: path.resolve(__dirname, 'src') },
  ...Object.entries(pkgPaths).map(([name, dir]) => createDynamicAlias(name, dir)),
  { find: '@foo/shared', replacement: path.resolve(__dirname, '../foo-shared/src') }
]

为什么vite-tsconfig-paths不生效？ #

该插件默认仅加载当前项目（即foo-bar）的tsconfig文件，不会扫描工作区中其他包的tsconfig路径规则。而foo-shared作为直接被引用的工作区包，其别名配置无法被插件识别，最终导致构建时解析错误。

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