TypeScript中如何向全局命名空间添加无需导入的全局函数

云上老周

2026-8-27

TypeScript 支持向全局命名空间添加自定义函数

你之前运行时找不到函数的核心原因：未将函数实际挂载到全局运行时对象上。
在无导出内容的.ts文件中直接定义函数时，现代TypeScript编译器及配套构建工具会默认将该文件识别为独立ES模块，模块内的顶层函数、变量作用域仅局限于当前文件内部，不会泄露到全局作用域，因此会出现编译阶段不报错、运行时找不到对应函数的情况。

正确实现步骤

第一步：编写全局类型声明
在TS配置include规则覆盖的目录下，新建全局类型声明文件（通常命名为global.d.ts），添加对应函数的类型签名，有两种合法写法：
1. 文件无任何import/export语句，直接声明全局函数（文件本身被识别为全局脚本）：
```
// global.d.ts 无任何导入导出
function myUtil<T>(input: T): T; // 替换为你自己的函数类型定义
```
2. 文件需要导入其他类型时，使用declare global块扩展全局命名空间，注意必须加至少一个export {}让TS识别当前文件为模块：
```
// global.d.ts
export {};
declare global {
  function myUtil<T>(input: T): T;
  // 多个全局函数可直接在块内追加声明
}
```
第二步：挂载运行时实现
在项目入口文件（如前端项目的main.ts、Node项目的入口index.ts）中，将函数实际实现挂载到全局对象上，跨环境推荐直接使用globalThis，无需区分浏览器的window或Node的global：
```
// 项目入口文件
globalThis.myUtil = function <T>(input: T): T {
  // 填写函数的实际业务逻辑
  return input;
};
```