Turborepo Monorepo开发模式下模块导出错误排查求助

以下是针对问题的具体排查方向和解决方案：

1. 检查内部包的核心配置 #

1.1 package.json 模块类型定义 #

确保每个@repo内部包的package.json明确指定模块规范：

{
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs" // 可选：兼容CommonJS环境
    }
  }
}

• type: "module" 告诉Vite和Node.js该包遵循ES模块规范，避免解析歧义。
• exports 字段精准定义不同导入方式的入口路径，确保开发/生产环境解析一致。

1.2 tsconfig.json 编译规则 #

内部包的tsconfig.json需保证编译产物为ES模块：

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "NodeNext",
    "target": "ES2020",
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

• module: "ESNext" 确保编译输出符合Vite开发环境的模块要求。
• moduleResolution: "NodeNext" 与type: "module"配合，正确解析ES模块的导入路径。

2. Vite应用配置优化 #

2.1 依赖预构建配置 #

在Vite应用的vite.config.ts中，强制预构建第三方包和内部包，避免直接解析未适配的CommonJS模块：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  optimizeDeps: {
    include: ['crypto-js', 'zustand', '@repo/utils', '@repo/ui', '@repo/auth']
  },
  resolve: {
    alias: {
      // 可选：若开发时直接引用内部包源码，需配置别名（依赖已通过Turborepo链接则无需）
      '@repo/utils': path.resolve(__dirname, '../packages/utils/src'),
      '@repo/ui': path.resolve(__dirname, '../packages/ui/src'),
      '@repo/auth': path.resolve(__dirname, '../packages/auth/src')
    }
  }
});

• optimizeDeps.include 让Vite将指定包预构建为ES模块，解决导出不匹配问题。

2.2 Turborepo 流水线配置 #

确保开发时内部包自动监听编译，在turbo.json中配置dev流水线依赖：

{
  "pipeline": {
    "dev": {
      "dependsOn": ["^dev"],
      "cache": false
    }
  }
}

并在每个内部包的package.json中添加监听命令：

{
  "scripts": {
    "dev": "tsc --watch"
  }
}

启动应用时，内部包会自动编译源码，保证应用引用的是最新的ES模块产物。

3. 第三方包导入适配 #

3.1 Crypto-JS 导出问题 #

若出现默认导出错误，可切换为命名导入：

import * as CryptoJS from 'crypto-js';

或通过Vite预构建自动转换（已在2.1中配置optimizeDeps.include: ['crypto-js']）。

3.2 Zustand 导出问题 #

使用标准ES模块导入方式，避免语法混用：

// 命名导入（推荐）
import { create } from 'zustand';
// 或默认导入（兼容部分版本）
import create from 'zustand';

预构建后Vite会自动处理Zustand的导出适配，无需额外修改。

4. 精准定位错误源 #

当出现导出错误时，通过浏览器控制台的错误栈定位具体文件：

• 若错误来自内部包产物：检查该包的tsconfig和package.json是否符合ES模块规范。
• 若错误来自第三方包：确认是否已加入optimizeDeps.include，或尝试更新包版本。

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