ts 在不同文件后缀中声明类型的区别

2025/07/04 2m #typescript

typescript 中在 .ts 和 .d.ts 文件中声明类型有什么区别？

TL;DR

type.ts 本地类型，外部无法使用

1
interface Test {}

type.ts 文件变成了模块，但由于没有导出，外部依然无法使用

1
export {}
2
interface Test {}

type.ts 在 ts 文件中以 declare 声明的类型，外部无法使用

1
declare interface Test {}

types.d.ts 在 d.ts 文件中声明的类型自动变为全局类型，外部无需导入即可访问

1
interface Test {}

types.d.ts 因为加入了 export ，文件变成了模块，类型外部不可访问

1
export {}
2
interface Test {}

types.d.ts 加入了 export ，文件变成了模块，类型外部可通过 import 导入访问

1
export interface Test {}

types.d.ts 加入了 declare ，文件变成了模块，但类型外部可通过 import 导入访问，与使用 export 效果相同

1
declare interface Test {}

types.d.ts 加入了 declare global ，但类型外部无法访问

1
declare global {
2
  interface Test {}
3
}

test.d.ts 加入了 declare global ，同时类型文件变成了模块，类型变为正常的全局类型

1
declare global {
2
  interface Window {
3
    aaa: string
4
  }
5
}
6
// 👇必须添加此行将当前文件转换为模块，否则全局类型不会生效
7
export {}

test.d.ts 为 NodeJS 的 process.env.xxx 补充类型，但前提是需要安装 @types/node 包才可以正常扩展 ProcessEnv 类型
```
1
declare global {
2
  interface ProcessEnv {
3
    readonly xxx: number
4
  }
5
}
```
test.ts 在 .ts 文件中声明的全局类型外部也可以正常识别

1
declare global {
2
  interface Window {
3
    aaa: string
4
  }
5
}

test.ts 在 .ts 文件中声明 node 的 process.env 类型，即便加了 export ，类型依然无法被外部访问，解决办法是改为 .d.ts 文件

1
declare namespace NodeJS {
2
  interface ProcessEnv {
3
    readonly ccc: number
4
  }
5
}
6

7
export { }

使用 .ts 文件声明类型在有些打包工具（例如 unbuild）的特殊配置下会生成一个空的 js 文件，但 .d.ts 文件则不会

1
import { defineBuildConfig } from 'unbuild'
2

3
export default defineBuildConfig({
4
  clean: true,
5
  declaration: true,
6
  entries: [
7
    {
8
      builder: 'mkdist',
9
      input: './src',
10
      pattern: ['**/*.ts'],
6 collapsed lines
11
      format: 'esm',
12
      loaders: ['js'],
13
      ext: 'js',
14
    },
15
  ],
16
})

回顾上一篇

接下来阅读