配置TypeScript包实现v1/v2版本子路径导出方案咨询

1. 调整源码目录结构 #

按照目标目录要求，将原有/lib/models拆分到/lib/v1/models和/lib/v2/models，同时在每个版本目录下新增index.ts作为入口，批量导出该版本的所有模块：

/lib
  /v1
    index.ts       # 统一导出v1的模型与服务
    /models
      my-first-model.ts
      ...
  /v2
    index.ts       # 统一导出v2的模型与服务
    /models
      my-first-model.ts
      ...

示例/lib/v1/index.ts内容：

export * from './models/my-first-model';
// 按需添加其他v1模块导出

/lib/v2/index.ts同理配置。

2. 配置package.json的exports字段 #

这是实现子路径导入的核心，通过exports字段定义不同子路径对应的编译后文件，同时兼容CommonJS和ES模块：

{
  "name": "@my-company/my-package",
  "version": "2.0.0", // 升级到v2版本，同时保留v1子路径兼容
  "type": "module",
  "main": "./dist/cjs/index.js",
  "module": "./dist/esm/index.js",
  "types": "./dist/types/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.js",
      "types": "./dist/types/index.d.ts"
    },
    "./v1": {
      "import": "./dist/esm/v1/index.js",
      "require": "./dist/cjs/v1/index.js",
      "types": "./dist/types/v1/index.d.ts"
    },
    "./v2": {
      "import": "./dist/esm/v2/index.js",
      "require": "./dist/cjs/v2/index.js",
      "types": "./dist/types/v2/index.d.ts"
    },
    "./v1/*": {
      "import": "./dist/esm/v1/*",
      "require": "./dist/cjs/v1/*",
      "types": "./dist/types/v1/*"
    },
    "./v2/*": {
      "import": "./dist/esm/v2/*",
      "require": "./dist/cjs/v2/*",
      "types": "./dist/types/v2/*"
    }
  },
  "files": [
    "dist"
  ]
}

• "./v1"和"./v2"对应根级子路径导入，满足import * from "@my-company/my-package/v1"的需求
• "./v1/*"和"./v2/*"支持深层子路径导入，比如import { MyFirstModel } from "@my-company/my-package/v1/models/my-first-model"
• types字段确保TypeScript能正确识别各子路径的类型定义

3. 配置TypeScript编译 #

修改tsconfig.json（ES模块编译配置）和tsconfig-cjs.json（CommonJS编译配置），确保编译后目录结构与源码对应：

tsconfig.json（ES模块） #

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "NodeNext",
    "declaration": true,
    "declarationDir": "./dist/types",
    "outDir": "./dist/esm",
    "rootDir": "./lib",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["lib/**/*"],
  "exclude": ["node_modules", "dist"]
}

tsconfig-cjs.json（CommonJS模块） #

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "CommonJS",
    "outDir": "./dist/cjs",
    "moduleResolution": "Node"
  }
}

在package.json的scripts中添加编译命令：

{
  "scripts": {
    "build": "npm run build:esm && npm run build:cjs",
    "build:esm": "tsc -p tsconfig.json",
    "build:cjs": "tsc -p tsconfig-cjs.json"
  }
}

执行npm run build后，dist目录会生成对应结构：

/dist
  /cjs
    /v1
      index.js
      /models
        my-first-model.js
    /v2
      index.js
      /models
        my-first-model.js
  /esm
    /v1
      index.js
      /models
        my-first-model.js
    /v2
      index.js
      /models
        my-first-model.js
  /types
    /v1
      index.d.ts
      /models
        my-first-model.d.ts
    /v2
      index.d.ts
      /models
        my-first-model.d.ts

4. 验证导入与类型提示 #

在其他项目中可按预期导入不同版本：

// file1.ts - 导入v1版本
import * as MyPackageV1 from "@my-company/my-package/v1";

function myFunction(myParamV1: MyPackageV1.MyFirstModel) {
  // 业务逻辑
}

// file2.ts - 导入v2版本
import * as MyPackageV2 from "@my-company/my-package/v2";

function anotherFunction(myParamV2: MyPackageV2.MyFirstModel) {
  // 业务逻辑
}

TypeScript会自动提供对应版本的类型提示，保证类型安全。

5. 发布到GitLab私有仓库 #

确保GitLab包仓库配置正确后，执行发布命令：

npm publish

注意：若之前已发布v1版本，本次发布需将package.json的version设为2.x.x，确保其他项目安装时获取到包含v1、v2子路径的最新包。

内容的提问来源于stack exchange，提问作者pcba-dev