如何配置VSCode编辑面向ES3的TypeScript并加载自定义@types声明

问题根因 #

TypeScript 解析typeRoots时，对于同名的类型包，只会返回第一个搜索到的匹配结果。你的两个类型根目录下都有@types文件夹，TS 找到第一个RulesetRunner_Declarations下的@types之后就终止搜索了，自然不会加载第二个RI_Declarations下的@types。同时 VSCode 不识别类型多和配置规则不匹配、TS 服务版本不一致有关。

解决方案 #

1. 调整配置与目录结构，解决多类型包加载问题 #

推荐采用更符合 TS 类型解析规则的目录结构调整方案，避免后续出现兼容问题：

第一步：调整目录结构

去掉每个声明文件夹下多余的@types嵌套，直接把每个声明文件夹作为独立类型包：

├── RulesetRunner_Declarations
│   ├── index.d.ts （原来@types下的index.d.ts，保留/// <reference>关联其他声明文件的逻辑）
│   ├── Iterator.d.ts （其他零散声明文件直接放在该目录下）
│   └── package.json （保留原配置，types字段指向./index.d.ts）
├── RI_Declarations
│   ├── index.d.ts
│   ├── 其他声明文件.d.ts
│   └── package.json （同上，types字段指向当前目录的index.d.ts）
└── 源码目录（ts2rr所在目录）
    └── tsconfig.json

第二步：修改tsconfig.json配置

{
    "compilerOptions": {
        "target": "es3",
        "lib": [
            "es5",
            "ScriptHost"
        ],
        "module": "none", // 你的环境无模块系统，改为none避免多余模块检查
        "typeRoots": [
            "../RulesetRunner_Declarations",
            "../RI_Declarations"
        ],
        // 显式指定要加载的两个类型包，TS会从typeRoots下逐个匹配对应目录
        "types": ["RulesetRunner_Declarations", "RI_Declarations"],
        "esModuleInterop": true,
        "forceConsistentCasingInFileNames": true,
        "strict": false,
        "skipLibCheck": true
    },
    // 显式包含声明文件路径，避免TS默认忽略上级目录文件
    "include": [
        "./**/*",
        "../RulesetRunner_Declarations/**/*",
        "../RI_Declarations/**/*"
    ]
}

如果你的业务代码是.js后缀而不是.ts后缀，需要在同级目录新增和上面配置完全一致的jsconfig.json，VSCode 对 JS 文件的类型检查默认读取jsconfig.json。

2. 解决VSCode类型不识别问题 #

• 确认所有.d.ts文件的声明没有加export关键字：加了export会变成模块声明，需要主动导入才能识别，不符合你全局类型的需求，直接写declare var Iterator: (a: any) => void;即可。
• 统一 TS 版本：打开任意 TS/JS 文件，点击编辑器右下角的 TS 版本号，选择「使用工作区版本」，避免 VSCode 内置版本和命令行版本不一致导致的解析差异。
• 重启 TS 服务：按Ctrl+Shift+P（Mac 为Cmd+Shift+P），执行「TypeScript: 重启TS服务器」，等待几秒后即可看到类型生效。

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