导入TypeScript项目时如何自动包含outDir配置的输出目录？

目前生态兼容性最好、维护成本最低的实现方式是通过package.json的exports字段做路径映射，不需要修改现有tsconfig的src/dist配置，也不需要库的消费端做额外设置。

核心配置 #

假设你的npm包名为your-library-name，直接在package.json中添加如下配置：

{
  "name": "your-library-name",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./*": {
      "import": "./dist/*.js",
      "require": "./dist/*.cjs",
      "types": "./dist/*.d.ts"
    }
  }
}

配置完成后，消费端直接写import { xyz } from "your-library-name/subdirectory/file"就会自动映射到dist目录下的对应文件，路径中不需要携带dist层级。

兼容性处理 #

• 该配置要求消费端TypeScript的moduleResolution设为bundler/node16/nodenext，这是当前TS官方推荐的默认配置，覆盖绝大多数2023年之后新建的项目场景。
• 如果需要兼容仍在使用node/node10旧模块解析策略的老项目，额外添加typesVersions字段解决类型路径识别问题即可：

  {
    "typesVersions": {
      "*": {
        "*": ["./dist/*"]
      }
    }
  }
  

  注意typesVersions仅处理TS类型的路径映射，运行时的路径解析依赖Node.js原生的exports能力，12.16.0之前的老版本Node不支持该特性，需要兼容这类环境可以用下面的替代方案。

旧环境替代方案 #

如果要兼容不支持exports字段的超老版本Node，可以在发布npm包时直接将dist目录作为包根发布：

• 编译完成后把package.json、README等发布需要的文件复制到dist目录
• 执行npm publish ./dist完成发布
  这种方式发布的包，根目录就是编译后的产物，导入路径自然不需要带dist，但缺点是本地monorepo联调时仍会遇到路径问题，维护成本更高，非必要不推荐。

避坑提示 #

• exports是白名单机制，配置./*通配规则后，dist下所有文件都可以被消费端导入，不要把内部未稳定的工具模块、敏感配置编译到dist公共目录。
• 不要要求消费端在自己的tsconfig里加paths映射解决路径问题，这是反模式，库本身应该抹平路径差异。
• 用tsup、rollup这类现代库构建工具的话，可以直接开启工具自带的exports自动生成能力，不用手写映射，减少出错概率。

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