如何解决TS2802错误：Map类型迭代需downlevelIteration或ES2015+目标

问题背景 #

多次尝试修复TS2802错误未果，已调整tsconfig.json中的downlevelIteration和target配置，也修改过package.json，但错误提示依旧。

当前配置与代码 #

tsconfig.json配置

{    
    "compilerOptions": {        
        "module": "commonjs",        
        "target": "es6",        
        // NZ 2022-09-09        
        "downlevelIteration": true,        
        "lib": ["DOM","ES6","ES2015.Collection","ES2015.Iterable"],        
        //--------------        
        "outDir": "dist",        
        "rootDir": ".",        
        "sourceMap": true,        
        "strict": false,        
        "composite": true    
    }
}

Map定义与触发错误的代码

Map结构定义：

interface outBrk {
    title: string;
    subTitle: string;
    // ...其他属性
}

type fldName = string;
const fields = new Map<fldName, keyof outBrk>([
    ['Title', 'title'],
    ['Sub-title', 'sub_title'],
    // ...其他键值对
]);

触发错误的迭代代码：

for (const [xlsxKey, jsonKey] of fields) {        
    if (jsonKey) {            
        if (jsonKey === 'vlnlist') {              
            // ...业务逻辑
        }
    }
}

错误提示

error TS2802: Type 'Map<string, keyof outBrk>' can only be iterated through when using the '--downlevelIteration' flag or with a '--target' of 'es2015' or higher.

248 for (const [xlsxKey, jsonKey] of fields) {
~~~~~~

排查与解决步骤 #

1. 升级TypeScript版本
   低版本TS对downlevelIteration的Map迭代支持存在bug，建议升级到3.8+版本：

   npm install typescript@latest --save-dev
   

2. 确认配置文件生效

   • 检查项目中是否存在多个tsconfig.*.json文件，TS可能加载了其他配置而非根目录的文件。
   • 执行tsc --showConfig查看当前生效的编译配置，确认target为es6（或es2015）且downlevelIteration为true。

3. 调整lib配置
   将lib中的ES6替换为ES2015（两者功能等价，但显式声明可避免解析歧义）：

   "lib": ["DOM","ES2015","ES2015.Collection","ES2015.Iterable"]
   

4. 检查编译命令是否覆盖配置
   查看package.json的scripts中的编译命令，比如tsc --target es5会直接覆盖tsconfig.json的设置，确保命令行未添加冲突参数。

5. 临时替代方案
   若以上方法无效，直接调用entries()方法获取迭代器：

   for (const [xlsxKey, jsonKey] of fields.entries()) {
       // ...原有业务逻辑
   }
   

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