TypeScript正确声明全局类型解决tsc找不到app类型报错

DevOps 小满

2026-8-26

问题根源

两个核心问题导致tsc编译报错、VSCode却能正常给出类型提示：

typeRoots 配置的加载逻辑不符合预期：TS默认只会加载typeRoots指定目录下子文件夹内的类型声明，不会直接扫描目录根路径下的.d.ts文件。VSCode内置的TS服务做了宽松适配，能识别到你放在types/app.d.ts的声明，但命令行执行tsc时严格遵循官方加载规则，找不到对应全局声明。
类型声明不完整：你只声明了全局的app接口，但没有显式将其挂载到Window接口上，TS不会自动把同名接口映射为window对象的属性类型，严格编译时就会抛出找不到名称的错误。

修复方案

第一步：修正类型文件加载配置

两种方案二选一即可：

方案1：保持现有typeRoots配置不变，调整类型文件存放路径，把types/app.d.ts移动到types/global/index.d.ts，TS会自动识别global子目录下的类型声明。
方案2：不调整文件路径，修改tsconfig.json配置，移除自定义的./types路径，改用include显式引入类型文件：

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types"]
  },
  "include": [
    "src/**/*", // 替换为你项目实际的业务代码路径
    "types/**/*.d.ts"
  ]
}

第二步：修正全局类型声明

修改类型文件内容，显式扩展Window接口，将app属性挂载到window类型上，建议类型名首字母大写，和实例变量做区分，符合TS命名规范：

export { };

declare global {
    interface Node { innerHTML: string }
    interface App {
        modules?: {
            [key: string]: string;
        },
        plugInLoader?: {
            installModule(jsContent: string): void,
            installBaseModules(): void,
            load(url: string): void,
            installerScript: Node,
        }
    }
    // 核心：显式扩展Window接口
    interface Window {
        app: App;
    }
}