[!info] related notes

• 所属 MOC: TypeScript MOC
• 配置入口: tsconfig 使用详解
• 并列概念: TypeScript 中的 .d.ts 声明文件, TypeScript 中的 declarationDir, TypeScript 中的 emitDeclarationOnly, TypeScript 中的 composite, TypeScript 中的 references

TypeScript 中的 declaration 与 declarationMap

一句话定义

• declaration：生成 .d.ts 类型声明文件
• declarationMap：为 .d.ts 生成映射，方便编辑器从声明跳回源码

核心机制 / 工作原理

declaration

打开后，TypeScript 会为每个源文件生成对应的 .d.ts，描述这个模块对外暴露的类型 API。

declarationMap

打开后，会额外生成 .d.ts.map，让编辑器在跨包跳转时更容易回到源码而不是只停在声明文件。

最小例子 / 最小场景

{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true
  }
}

常见用途

• npm library 对外发布类型
• monorepo 中让别的包消费类型定义
• project references 下提升跨包跳转体验

边界与易混淆点

declaration 不是运行时产物

.d.ts 只服务于类型系统和编辑器，不会在运行时执行。

declarationMap 更偏开发体验

它通常不改变类型语义，但会明显改善：

• Go to Definition
• Rename
• 跨包跳回源码

声明文件的输出位置和输出范围还可以继续细分

如果你需要继续拆这层：

• declarationDir 负责 .d.ts 放到哪里
• emitDeclarationOnly 负责是否只生成声明而不生成 JS

composite 常常会把 declaration 变成必需项

在 project references 场景里，declaration 基本是核心前提之一。

参考信息

• TSConfig declaration: https://www.typescriptlang.org/tsconfig/#declaration
• TSConfig declarationMap: https://www.typescriptlang.org/tsconfig/#declarationMap
• Project References: https://www.typescriptlang.org/docs/handbook/project-references