TypeScript同目录下同名.ts与.d.ts文件类型失效问题及原理咨询

嗨，我来给你拆解一下这个问题背后的TypeScript规则逻辑，你遇到的情况其实是TS处理同名文件时的一个特定行为，咱们一步步理清楚：

核心原因：TS对同名.ts和.d.ts的优先级与角色定义 #

当同目录下存在同名的实现文件（比如index.ts）和声明文件（index.d.ts）时，TypeScript会默认把.d.ts文件当作对应.ts文件的专属类型声明文件，而不是独立的全局声明文件。这时候就会触发两种不同的处理逻辑：

• 如果你的.ts文件是模块（也就是包含import/export语句），那.d.ts里的声明会被当作这个模块的类型补充，但全局作用域的声明（比如扩展Window接口）需要用declare global包裹才能生效；
• 但如果你的.ts文件是全局脚本（没有任何import/export），TS就不会把.d.ts里的全局声明合并到全局作用域里——因为它默认这个.d.ts是给同名.ts文件服务的，而不是全局生效的，这就导致你在index.ts里访问window.a时找不到类型。

为什么改名成不同名字就生效了？ #

当你把两个文件改成不同名字（比如index.ts和anotherindex.d.ts），.d.ts就脱离了“专属类型声明”的绑定，变成了一个独立的全局声明文件。再加上你的tsconfig.json里已经配置了include所有.d.ts文件，TS会自动扫描并加载这个全局声明，所以Window接口的扩展就正常生效了。

三斜线指令为什么能解决问题？ #

你添加的/// <reference path="./index.d.ts" />是TypeScript的一个显式声明引用指令，它的作用是强制告诉TS：“当前文件必须加载这个指定的声明文件”，直接绕过了同名文件的优先级规则。不管.d.ts是不是和.ts同名，只要加了这个指令，TS就会把这个.d.ts里的内容（包括全局接口扩展）加载到当前文件的作用域里，所以window.a的类型就被识别到了。

额外的解决思路：把脚本改成模块 #

如果不想改名也不想加三斜线指令，还有一种方法：给你的index.ts添加一个空的导出语句，把它变成模块：

// src/index.ts
export {}; // 把文件变成模块
console.log('window.a :>> ', window.a);

同时修改对应的index.d.ts，用declare global包裹全局声明：

// src/index.d.ts
declare global {
  interface Window {
    a: number;
  }
}
export {}; // 必须加导出，让文件成为模块

这样TS会正确识别.d.ts里的全局扩展，同时保持两个文件同名的结构。

备注：内容来源于stack exchange，提问作者Bryan Adamss