全局类型定义失效的根本原因是声明文件未被 typescript 加载：需检查 tsconfig.json 的 include/typeroots 是否覆盖声明路径，确认 .d.ts 文件无 export/import，运行 tsc --traceresolution 验证扫描日志，并排除 @types/ 同名包冲突。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
在 TypeScript 项目中，全局类型定义失效会导致 VS Code 无提示、tsc 编译报错、window 或 global 上挂载的属性被识别为不存在——这些问题往往不是代码写错了，而是类型声明没被编译器“看见”。CodeBuddy 提供了三类可验证、可定位、可修复的检查路径，覆盖从声明位置、加载时机到作用域范围的全链路。
确认全局声明文件是否被 TypeScript 主动加载
第一步：检查 【tsconfig.json】 中是否将声明文件所在目录纳入 typeRoots 或 include 范围。若声明文件放在 src/types/global.d.ts，但 tsconfig.json 的 "include" 字段只写了 ["src/**/*"]，则它会被包含；但如果写成 ["src/index.ts"]，该 .d.ts 文件将彻底被忽略。
第二步：运行 tsc --traceResolution 命令，观察控制台输出中是否有类似 “Found 'global.d.ts' at …” 的日志行。没有这条日志，说明 TypeScript 根本没扫描到该文件。
第三步：确保该 .d.ts 文件【不包含任何 export 或 import 语句】。一旦出现 export {} 或 import，TypeScript 就会把它当作模块文件处理，declare global 块将失效。
验证 declare global 声明是否处于正确作用域
方法一：在任意 .ts 文件中输入 window.，触发 VS Code 智能提示，看是否列出你声明的属性（如 myApi、__DEV__）。没出现，说明声明未生效。
方法二：在声明文件中临时添加一句非法语法，比如 const x: any = ;（缺少右值），然后运行 tsc --noEmit。如果报错位置指向该 .d.ts 文件，说明它已被加载；如果不报错，证明文件根本没参与编译。
方法三：打开 VS Code 的命令面板（Ctrl+Shift+P），输入 “TypeScript: Restart TS Server”，强制刷新类型服务缓存。旧缓存可能卡住已修改但未重载的 global 声明。
排查第三方库全局类型是否被覆盖或冲突
打开 node_modules/@types/ 目录，检查是否存在与你自定义声明同名的包（例如你写了 declare module 'echarts'，但同时安装了 @types/echarts）。后者会优先被加载，导致你的声明被完全忽略。
运行 npm ls @types/echarts（或其他冲突库名），确认是否安装了官方类型包。如果存在，且你确需覆盖其类型，可在 tsconfig.json 的 compilerOptions 中添加："typeRoots": ["./src/types", "./node_modules/@types"]，把自定义路径放在前面。
注意：若你用的是 pnpm 或 yarn pnp，还需确认 .d.ts 文件是否被符号链接正确解析——某些情况下，pnpm 的 hard link 机制会让 TypeScript 误判文件归属，此时需在 tsconfig.json 中显式设置 "rootDir": "."。
用 CodeBuddy 快速诊断全局类型加载状态
在 CodeBuddy IDE 插件中，右键点击任意 .d.ts 声明文件 → 选择 “Analyze Global Declaration Scope”。它会自动执行三步检测：① 是否被 tsconfig 包含；② 是否含非法模块语法；③ 是否与 node_modules/@types 下同名声明冲突。
检测完成后，界面直接高亮显示问题根源，并给出可点击的修复建议链接，例如跳转到 tsconfig.json 修改 include 字段，或一键删除冗余的 @types 包。
这一步操作起来很简单，直接点击分析按钮就行，无需手动查日志或翻配置。
