梳理Monorepo中TypeScript模块解析与配置问题

环境与结构 #

我用npm workspaces搭建了Monorepo，所有包都使用TypeScript 4.7，目录结构如下：

root
  apps
    nestjs
      tsconfig.json
    cloud_functions
      tsconfig.json
    frontend (vue3)
      tsconfig.json
  packages
    types
      tsconfig.json
      package.json
    config
      tsconfig.json
      package.json

需求是从config包导入常量，从types包导入类型，目前类型导入正常，但常量导入存在问题。

消费端tsconfig基础配置 #

所有消费端的tsconfig.json均包含如下配置：

{
  "extends": "@app/tsconfig/tsconfig.base.json",
  "compilerOptions": {
    "rootDir": ".",
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@app/types": ["../../packages/types"],
      "@app/config": ["../../packages/config"]
    }
    //... 其他配置

  },
  
  "references": [
    { "path": "../../packages/types/tsconfig.json" },
    {
      "path": "../../packages/config/tsconfig.json"
    }
   //... 其他配置
  ]
}

不同消费端模块规范 #

• NestJS/Cloud Functions：采用CommonJS规范，tsconfig核心配置：

"compilerOptions": {
  "module": "CommonJS",
  "moduleResolution": "Node",
 // ... 其他配置
}

• Vue3：采用ESNext规范，tsconfig核心配置：

"compilerOptions": {
  "module": "ESNext",
  "moduleResolution": "Node",
 // ... 其他配置
}

Vue3默认已开启"esModuleInterop": true，且NestJS无法改为ESNext规范，必须保留CommonJS。

config包当前配置 #

tsconfig.json

{
  "extends": "@app/tsconfig/tsconfig.base",
  "compilerOptions": {
    "esModuleInterop": true,
    "module": "CommonJS",
    "target": "es6",
    "skipLibCheck": true,
    "allowSyntheticDefaultImports": true,
    "types": ["node"]
  },
  "include": ["./index.ts", "./src/**/*.ts"],
  "display": "Config"
}

package.json

{
  "name": "@app/config",
  "version": "0.0.1",
  "license": "MIT",
  "scripts": {
    "build": "tsc -b"
  },
  "exports": "./index.js",
  "types": "index.d.ts",
  "private": true
}

问题现象 #

编译后的config包代码中明明存在：

Object.defineProperty(exports, "CASL_SUBJECT_ACCOUNT", { enumerable: true, get: function () { return casl_1.CASL_SUBJECT_ACCOUNT; } });

但Vue3导入时报错：

/packages/config/index.js' does not provide an export named 'CASL_SUBJECT_ACCOUNT'

曾尝试设置emitDeclarationOnly: true让消费端自行编译，但引发其他问题。

问题解答 #

1. 是否可依赖"references"配置，无需将packages作为依赖导入？ #

可以。TypeScript的Project References（references配置）专为Monorepo设计，用于建立包之间的编译依赖关系，无需在package.json的dependencies/devDependencies中声明内部包。但需确保：

• 被引用的包的tsconfig必须设置composite: true（当前config包未配置，需补充）
• 消费端使用tsc -b（增量编译）触发整个依赖链的编译

2. config包是否必须生成JavaScript文件？ #

是的。types包仅提供类型声明（可使用emitDeclarationOnly），但config包包含运行时常量，属于可执行代码，必须生成JS文件供消费端运行时加载。让消费端自行编译会导致重复编译、模块规范不匹配等问题，反而更复杂。

3. 是否需要将常量导出为.cjs/.mjs文件，还是可通过TypeScript内置配置（如esModuleInterop）解决？ #

不需要单独生成.cjs/.mjs文件，通过TypeScript配置和package.json的模块声明即可解决。问题核心是CommonJS模块的命名导出在ES模块中的识别逻辑，只需让Node.js模块解析器正确识别CommonJS包即可。

4. 如何修改现有配置以解决当前报错？ #

按以下步骤调整：

步骤1：完善config包的tsconfig.json

添加composite: true（Project References必填），确保declaration: true（生成类型声明）：

{
  "extends": "@app/tsconfig/tsconfig.base",
  "compilerOptions": {
    "esModuleInterop": true,
    "module": "CommonJS",
    "target": "es6",
    "skipLibCheck": true,
    "allowSyntheticDefaultImports": true,
    "types": ["node"],
    "composite": true, // 新增，启用Project References支持
    "declaration": true // 确保生成类型声明，已有则忽略
  },
  "include": ["./index.ts", "./src/**/*.ts"],
  "display": "Config"
}

步骤2：修改config包的package.json，明确模块类型

添加"type": "commonjs"声明包类型，同时优化exports字段兼容ES模块和CommonJS导入：

{
  "name": "@app/config",
  "version": "0.0.1",
  "license": "MIT",
  "scripts": {
    "build": "tsc -b"
  },
  "type": "commonjs", // 新增，明确模块类型
  "exports": {
    ".": {
      "import": "./index.js",
      "require": "./index.js"
    }
  }, // 优化exports，明确不同导入方式的入口
  "types": "index.d.ts",
  "private": true
}

步骤3：调整Vue3端的配置与导入方式

确保Vue3的tsconfig.json中allowSyntheticDefaultImports: true和esModuleInterop: true均开启，若仍有问题，可临时将命名导入改为默认导入后解构：

// 原导入方式
import { CASL_SUBJECT_ACCOUNT } from '@app/config';

// 临时兼容写法（配置正确后可改回）
import config from '@app/config';
const { CASL_SUBJECT_ACCOUNT } = config;

步骤4：确保编译顺序正确

在根目录或消费端目录执行tsc -b，确保config包先编译完成，再编译Vue3等消费端。

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