如何在NodeJS Express的global.d.ts中声明全局UtilService

你仅在global.d.ts中声明了UtilService的类型，让TypeScript认可这个全局变量的存在，但运行时Node.js的全局对象（global）上并没有实际挂载UtilService的类或实例，因此会出现"未定义"的运行时错误。

1. 调整全局类型声明 #

修改global.d.ts，确保类型声明正确扩展Node.js全局作用域，同时将文件标记为模块（否则declare global不会生效）：

import { UtilService } from './src/services/utilService';

declare global {
    var UtilService: UtilService;
}

// 标记为ES模块，确保全局声明生效
export {};

如果不想在声明文件中导入，也可以直接引用类型：

declare global {
  namespace NodeJS {
    interface Global {
      UtilService: typeof import('./src/services/utilService').UtilService;
    }
  }
}

export {};

2. 手动挂载服务到全局对象 #

在项目入口文件（比如src/app.ts）中，导入UtilService并挂载到Node.js的global对象上，保证运行时能访问到：

import { UtilService } from './services/utilService';

// 挂载到全局对象
global.UtilService = UtilService;

// 后续Express初始化逻辑
import express from 'express';
const app = express();
// ...

3. 优化tsconfig配置（可选） #

当前tsconfig.json的files数组仅包含两个文件，虽然app.ts已导入utilService.ts不会影响编译，但用include字段覆盖所有源码文件更灵活：

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "declaration": true,
    "outDir": "dist",
    "typeRoots": ["./node_modules/@types", "./"] // 确保全局类型文件被识别
  },
  "include": ["src/**/*", "global.d.ts"],
  "exclude": ["node_modules", "dist"]
}

4. 验证调用 #

现在可以在任意文件中直接调用：

UtilService.doSomeThing();

• TypeScript的全局类型声明仅负责类型校验，不处理运行时的变量挂载，必须手动将类/实例挂载到全局对象上。
• Node.js环境的全局对象是global，浏览器环境是window，可使用globalThis实现跨环境兼容。

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