将TypeScript源码作为库的类型声明分发存在哪些问题？

常规TypeScript库的发布流程，都是用tsc把TS源码编译成JS，同时生成.d.ts声明文件，再在package.json的exports里把types指向编译好的dist/index.d.ts。

现在有人尝试跳过生成声明文件，直接把types指向项目源码，配置示例如下：

// package.json
{
  //...
  "exports": {
    "types": "./src/index.ts",
    "default": "./dist/index.js"
  }
}

这种做法确实有好处：

• CI里只用tsc做类型检查，编译交给更快的swc处理，提升构建速度
• monorepo场景下，不用配置tsconfig#paths别名，IDE会直接把源码当类型文件识别，减少配置麻烦

但这种方式存在不少坑，具体如下：

一、JSDoc相关问题 #

• TS专属JSDoc标签兼容性差：如果源码里用了TypeScript扩展的JSDoc标签（比如@template、带TS类型的@param），消费方的TS版本如果比你的库低，大概率解析不了这些标签，导致类型提示乱掉。
• API文档生成异常：像TypeDoc这类自动生成API文档的工具，默认是基于.d.ts文件的。直接用源码的话，要么需要额外复杂配置，要么会因为源码里的实现代码干扰文档生成，比如把内部临时变量也当成API输出。

二、tsconfig配置冲突问题 #

• 编译选项打架：你的库的tsconfig.json里的配置（比如strict、moduleResolution、lib）可能和消费方的tsconfig完全不一样。TS解析源码类型时，会优先用库目录下的tsconfig，这会导致消费方的类型检查行为偏离预期。比如你的库开了strictNullChecks，消费方没开，那消费方用你的库时会莫名其妙出现很多空值类型错误。
• 内部路径解析失败：如果源码里用了相对路径导入内部模块（比如./utils/helper），发布到npm后，消费方的项目结构和你的库源码结构不一样，TS解析这些路径时会找不到文件，直接报类型错误——monorepo里没问题是因为目录结构一致，但发布后就会出问题。

三、其他隐藏问题 #

• 类型解析变慢：TS解析完整的TS源码比解析精简的.d.ts文件慢得多，大型库会直接拖慢消费方的IDE提示和类型检查速度，开发体验下降。
• 源码细节泄露：虽然你发布的是编译后的JS，但把types指向源码等于把完整源码暴露给消费方，内部逻辑、未公开的工具函数都会被看到，如果你不想公开这些细节，这就是个大问题。
• TS版本兼容问题：不同版本的TS对源码的解析规则有差异，尤其是新语法和特性。如果你的库用了较新的TS特性，低版本TS的消费方根本解析不了源码类型，而.d.ts文件只要编译时指定了目标版本，通常能向下兼容。

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