TypeScript中URLSearchParams传字符串使用时触发ts(2769)报错

报错和URLSearchParams构造函数接收字符串入参的能力无关，核心是当前TypeScript环境加载的URLSearchParams类型定义缺失迭代器相关声明，常见触发场景有两种：

• URLSearchParams实例实现[Symbol.iterator]接口、可直接传入Object.fromEntries是ES2018标准纳入的特性。如果项目tsconfig.json中编译目标target低于ES2018，且没有手动在lib配置中引入ES2018及以上的标准库声明，TS会加载旧版本类型定义，也就是你查到的那份不包含迭代器实现的声明，自然会判定实例不满足Object.fromEntries的入参要求。
• Node.js环境下，如果安装的@types/node版本过旧，也会出现类型定义不全的问题。

根据项目兼容场景选择对应方案即可：

方案1：修正TS配置（推荐） #

如果代码运行环境（Node.js 10+、所有现代浏览器）原生支持URLSearchParams的迭代特性，直接调整tsconfig.json的编译配置即可：

{
  "compilerOptions": {
    // 编译目标设为ES2018及以上，可选值：ES2019、ES2020、ESNext
    "target": "ES2020",
    // 若不想修改target，也可以手动在lib数组中追加高版本ES库，浏览器环境需追加DOM，Node环境搭配对应版本的@types/node使用
    "lib": ["ES2020", "DOM"]
  }
}

Node.js项目同步将本地的@types/node升级到和运行时Node版本匹配的新版本即可。

方案2：类型断言适配（无法修改全局配置时使用） #

如果不方便调整全局TS配置，且确认运行环境支持迭代特性，可以直接用类型断言临时修正类型：

const sortString = req.query.sort as string
const params = Object.fromEntries(
  new URLSearchParams(sortString) as Iterable<[string, string]>
)

方案3：兼容写法（适配低版本运行环境） #

如果需要兼容不支持URLSearchParams迭代器的老旧环境，可以不依赖迭代器能力，手动遍历生成对象，兼容性最好：

const sortString = req.query.sort as string
const searchParams = new URLSearchParams(sortString)
const params: Record<string, string> = {}
searchParams.forEach((value, key) => {
  params[key] = value
})

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