仅含TypeScript模型的NPM包结构配置及子路径导入实现方案

要实现import { User } from '@org/project-name/users'这类按文件夹路径导入的效果，不需要额外引入rollup、tsup等打包工具，靠TypeScript官方编译器+package.json标准字段配置就能实现，你现有的模型文件夹聚合导出的写法完全可以保留，具体操作如下：

1. 统一源码目录结构 #

先把所有模型源码收拢到src目录下，保持你现有的单文件定义+目录index聚合的写法，最终结构参考：

包根目录/
├── src/
│   ├── index.ts          # 包根入口，可选，用于全量导出所有类型
│   ├── users/
│   │   ├── user.ts       # 单类型定义：export type User = {...}
│   │   └── index.ts      # 聚合导出：export { User } from './user'
│   ├── organizations/
│   │   ├── organization.ts
│   │   └── index.ts
│   └── [其他模型文件夹]/
│       ├── xxx.ts
│       └── index.ts
├── package.json
└── tsconfig.json

2. 调整tsconfig.json配置 #

纯类型包不需要复杂的编译配置，直接用下面的参数即可，不要额外配置paths路径映射——那是项目内部导入用的，对外发布的包配paths没有任何作用：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler", // 必须配置为Bundler或NodeNext，否则无法识别package.json的exports规则
    "declaration": true, // 必须开启，用于生成.d.ts类型声明文件
    "declarationDir": "./dist",
    "outDir": "./dist",
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

3. 核心配置：package.json的exports字段 #

这是实现子路径导入的关键，通过exports字段可以明确告诉包管理器、TS编译器每个导入路径对应的文件位置，配置示例：

{
  "name": "@org/project-name",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"], // 发布时只上传dist目录，避免把源码、配置文件打到包里
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./users": {
      "import": "./dist/users/index.js",
      "types": "./dist/users/index.d.ts"
    },
    "./organizations": {
      "import": "./dist/organizations/index.js",
      "types": "./dist/organizations/index.d.ts"
    }
    // 后续新增模型文件夹，在这里追加对应配置即可
  },
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build" // 发布前自动执行编译，避免漏打最新代码
  }
}

如果模型文件夹数量很多，不想手动维护exports列表，可以写个几十行的简单脚本，在build阶段自动扫描src下的一级目录生成exports配置，不需要额外依赖第三方工具。

4. 构建与发布验证 #

• 本地执行npm run build，确认dist目录下的文件结构和src完全一致，每个模型文件夹下的index.js、index.d.ts都正常生成
• 执行npm pack生成本地测试包，在其他业务项目里安装这个本地包，验证import { User } from '@org/project-name/users'能正常识别类型、无报错
• 验证通过后正常发布到npm或GitHub Packages即可

避坑提醒 #

• 不要用旧版的typesVersions字段做子路径类型映射，目前所有维护中的Node版本、现代打包器都原生支持exports里的types字段，写法更统一，不会出现类型和实际导入路径不一致的问题
• 不要直接把.ts源码发布到npm供外部导入，必须编译生成.d.ts声明文件，否则依赖方的TS配置可能出现类型解析失败的问题
• 编译时不要修改输出目录的结构，确保dist下的路径和src下的路径一一对应，否则exports里配置的路径会找不到文件
• 子路径配置不要画蛇添足加/index后缀，直接写./users即可，Node和打包器会自动识别目录下的index入口文件

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