编译后的Lerna项目无法解析公共库包模块求助

问题根源 #

TypeScript 的 paths 配置仅在编译阶段生效，编译后的 JavaScript 代码中，Node.js 无法识别 @bdc/common/* 这类别名；同时当前配置存在两个关键问题：

• bdc-server 的 paths 指向 bdc-common 的源码目录，而非编译后的 dist 产物
• 未通过 npm workspaces 正确声明本地包依赖，Node.js 运行时无法找到本地包的入口

步骤1：修复 bdc-common 配置 #

更新 bdc-common/package.json #

添加 main、types 字段指定编译后产物入口，同时用 files 字段明确包含产物目录：

{
  "name": "@bdc/common",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "tsc",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "dependencies": {
    "pg": "^8.11.0",
    "pg-hstore": "^2.3.4",
    "sequelize": "^6.32.0"
  }
}

若没有统一的 index.ts 导出入口，可直接指定具体文件路径，比如 "main": "dist/database/sequelize.js"

调整 bdc-common/tsconfig.json #

将 rootDir 指向源码目录（假设源码在 src 下），避免编译后目录结构混乱：

{
  "compilerOptions": {
    "target": "esnext",
    "module": "commonjs",
    "lib": ["esnext", "dom"],
    "esModuleInterop": true,
    "outDir": "dist",
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "strict": true,
    "skipLibCheck": true,
    "composite": true,
    "rootDir": "./src",
    "paths": {
      "@bdc/common/*": ["./src/*"]
    }
  },
  "exclude": ["node_modules", "dist"],
  "include": ["src/**/*"]
}

步骤2：修复 bdc-server 配置 #

1. 声明本地包依赖 #

在 bdc-server/package.json 中添加 @bdc/common 的依赖，npm workspaces 会自动在 node_modules 中创建软链：

{
  "name": "@bdc/server",
  "version": "1.0.0",
  "dependencies": {
    "@bdc/common": "^1.0.0",
    // 其他依赖...
  }
}

2. 优化 TS 配置（二选一） #

方案A：直接使用包名导入（推荐）

删除 bdc-server/tsconfig.json 中的 paths 配置，直接通过包名导入模块：

// 替换之前的路径导入
import sequelize from "@bdc/common/database/sequelize";

保留 references 确保编译顺序：

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "outDir": "dist",
    "strict": true,
    "baseUrl": ".",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "useUnknownInCatchVariables": false
  },
  "references": [
    {
      "path": "../bdc-common"
    }
  ],
  "include": ["src/**/*.ts"]
}

方案B：保留 paths 但指向 dist 目录

若必须保留别名，修改 paths 指向编译产物，同时添加运行时解析工具：

{
  "compilerOptions": {
    // 其他配置不变
    "paths": {
      "@bdc/common/*": ["../bdc-common/dist/*"]
    }
  }
}

安装 module-alias 包，在 bdc-server 入口文件顶部添加：

import 'module-alias/register';

并在 bdc-server/package.json 中添加别名映射：

{
  "_moduleAliases": {
    "@bdc/common": "../bdc-common/dist"
  }
}

步骤3：确保正确的构建顺序 #

使用 Lerna 按依赖顺序编译：

lerna run build --scope @bdc/common --scope @bdc/server

或在根目录 package.json 添加统一构建脚本：

{
  "scripts": {
    "build": "lerna run build --sort"
  }
}

验证运行 #

1. 根目录执行 npm install，确保本地包软链正确
2. 执行 npm run build 编译所有包
3. 进入 bdc-server 目录执行 npm start，即可正常加载公共模块

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