基础Node.js+TypeScript项目中无法扩展ProcessEnv接口

以下是几个关键的排查和修复步骤：

1. 修正声明文件后缀 #

TypeScript的全局类型增强文件必须使用.d.ts后缀，而非普通的.ts。你的node.augmentations.ts会被当作普通脚本文件处理，无法生效。将文件名改为node.augmentations.d.ts。

2. 检查tsconfig.json的文件扫描配置 #

确保tsconfig.json的include数组包含你的声明文件，让TypeScript能识别到它。例如：

{
  "compilerOptions": {
    // 其他配置...
  },
  "include": ["src/**/*", "*.d.ts"]
}

如果你的声明文件在子目录，也要对应调整include路径。

3. 避免将声明文件变为模块 #

如果你的.d.ts文件中存在import或export语句，它会被视为模块，全局的NodeJS命名空间扩展将失效。此时需要用declare global包裹增强代码，并添加空导出：

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      HOST: string;
    }
  }
}

// 空导出确保文件被识别为模块，同时global声明生效
export {};

4. 重启TypeScript语言服务 #

编辑器的TypeScript服务可能缓存了旧的类型信息，修改文件或配置后，重启服务（比如VSCode中按Ctrl+Shift+P，选择「TypeScript: Restart TS Server」），让新的类型声明生效。

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