TypeScript的.d.ts文件中export与declare修饰符及四种type声明差异

核心前提：.d.ts 的两种上下文 #

.d.ts 文件分为两种作用域模式，这是理解所有声明行为的基础：

• 全局上下文：文件中没有任何 import/export 语句，所有顶层声明默认属于全局作用域，整个项目可直接使用。
• 模块上下文：文件包含 import/export 语句，自动转为 ES 模块模式，所有顶层声明默认是模块私有，仅能在模块内部使用，需通过 export 暴露给外部。

四种类型声明的行为与适用场景 #

1. type #

• 行为：
  • 若处于全局上下文：该类型是全局可用的，项目中任何文件无需 import 即可直接引用。
  • 若处于模块上下文：该类型是模块内私有，外部文件无法通过 import 引用（你提到能导入的情况大概率是误解——要么该文件实际是全局上下文，要么是通过其他全局声明方式间接引用）。
• 适用场景：
  • 定义项目全局通用的类型（需确保文件无 import/export）；
  • 模块内部仅需自用的私有类型。

2. export type #

• 行为：
  • 只要使用 export，文件自动进入模块上下文。该类型是模块的公开导出成员，外部文件必须通过 import { 类型名 } from './xxx.d.ts' 才能引用。
• 适用场景：
  • 组织模块化的声明文件，拆分类型为不同模块，避免全局污染；
  • 开发库时，对外暴露库的公开类型接口；
  • 项目内部共享的非全局类型，通过模块导入导出复用。

3. declare type #

• 行为：
  • 仅在全局上下文（或 declare global 块内）生效，明确声明一个全局类型，整个项目无需 import 即可直接使用。
  • 注意：在模块上下文里直接写 declare type 无效，必须包裹在 declare global { ... } 块中才能声明全局类型。
• 适用场景：
  • 定义全局环境的类型（比如浏览器原生 API 的扩展类型、全局变量对应的类型）；
  • 项目中需要全量复用、无需导入的基础类型。

4. export declare type #

• 行为：
  • 本质是在模块上下文中，明确声明一个类型并将其导出。在.d.ts 文件中，顶层 type 声明本身就隐含了 declare（因为.d.ts 仅做声明），所以它和 export type 的实际运行效果完全一致，只是语义上更强调这是一个“外部存在的类型声明”。
• 适用场景：
  • 开发第三方库的声明文件时，语义化地标记导出的类型是对外声明的接口；
  • 在模块内声明需要导出的类型，同时明确表达“这是一个声明而非实现”的意图（虽然.d.ts 本身都是声明，但这种写法更清晰）。

常见疑问解答 #

• 为什么我能导入未加 export 的 type？
  大概率是该文件没有 import/export 语句，处于全局上下文——你看似是“导入”，实际是直接引用了全局类型，而非模块导入。
• export 仅在开发库时有用？
  不是。哪怕是普通项目，当你需要拆分声明文件、避免全局类型污染、按模块组织类型时，export 是必要的，能让类型复用更规范。

内容的提问来源于stack exchange，提问作者Emre Akı