如何在Yarn Workspaces中使用Vite？解决运行时模块加载异常

问题背景 #

项目采用Yarn Workspaces（yarn@3.3.1）结构：

packages
   package-a
   package-b

根目录package.json工作区配置：

{
  "...": "...",
  "workspaces": [
    "packages/package-a",
    "packages/package-b"
  ],
  "...": "...",
  "packageManager": "yarn@3.3.1"
}

package-b通过workspace:协议引用package-a：

{
  "...": "...",
  "dependencies": {
    "...": "...",
    "package-a-name-in-npm": "workspace:packages/package-a"
  },
  "...": "..."
}

运行Vite应用时抛出浏览器运行时错误：

Uncaught SyntaxError: The requested module ... does not provide an export named ...

但TypeScript、ESLint对导入语句无报错。

排查与解决方案 #

1. 检查package-a的模块入口配置 #

Vite优先识别ES模块，若package-a的package.json未正确配置入口字段，会导致Vite加载错误的文件。

解决步骤：

• 确保package-a的package.json包含以下字段（根据编译产物调整路径）：

  {
    "main": "./dist/package-a.cjs.js", // CommonJS入口（兼容Node.js）
    "module": "./dist/package-a.esm.js", // ES模块入口（Vite优先加载）
    "types": "./dist/index.d.ts", // TypeScript类型定义
    "exports": { // 更明确的入口映射（推荐）
      ".": {
        "import": "./dist/package-a.esm.js",
        "require": "./dist/package-a.cjs.js",
        "types": "./dist/index.d.ts"
      }
    }
  }
  

• 确认package-a已执行编译命令，dist目录存在对应产物。

2. 配置Vite解析工作区包 #

Vite默认可能未正确处理Yarn Workspaces的软链接，导致加载未编译的源码或路径错误。

解决步骤：
在package-b的vite.config.ts中添加以下配置：

import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    // 直接映射包名到package-a的编译产物入口
    alias: {
      'package-a-name-in-npm': '../../packages/package-a/dist/package-a.esm.js'
    }
  },
  optimizeDeps: {
    // 强制Vite预构建工作区包
    include: ['package-a-name-in-npm'],
    // 若package-a源码是TypeScript，添加esbuild的TS支持
    esbuildOptions: {
      loader: { '.ts': 'ts' }
    }
  }
});

3. 验证package-a的导出与编译配置 #

若package-a的源码导出方式与package-b的导入方式不匹配，或编译配置错误，会导致导出不存在。

解决步骤：

• 检查package-a源码的导出：
  • 若package-b用import { XXX } from 'package-a-name-in-npm'，确保package-a源码中有export const XXX = ...的命名导出
  • 若用默认导入import XXX from 'package-a-name-in-npm'，确保package-a有export default XXX
• 检查package-a的tsconfig.json：

  {
    "compilerOptions": {
      "module": "ESNext", // 输出ES模块
      "declaration": true, // 生成类型定义
      "outDir": "./dist", // 编译产物输出目录
      "target": "ESNext"
    }
  }
  

4. 处理Yarn PnP兼容性问题 #

Yarn v3默认启用PnP模式，Vite原生支持有限，可能导致包解析失败。

解决步骤：

方案一：启用Vite的PnP插件

• 安装插件：

  yarn add @vitejs/plugin-yarn-pnp -D
  

• 在vite.config.ts中启用：

  import { defineConfig } from 'vite';
  import yarnPnp from '@vitejs/plugin-yarn-pnp';
  
  export default defineConfig({
    plugins: [yarnPnp()]
  });
  

方案二：切换到node_modules模式

• 在根目录的.yarnrc.yml中修改：

  nodeLinker: node-modules
  

• 重新执行yarn install生成node_modules目录。

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