编写同构TypeScript包时如何使用URLSearchParams及同类API？

开发者阿泽

2026-6-15

解决同构TypeScript包中使用URLSearchParams的类型问题

方案1：引入@types/web类型依赖

@types/web包含浏览器标准API的类型定义（包括URLSearchParams），且不会引入DOM非核心API，适配同构场景。安装后无需修改tsconfig，TypeScript会自动识别这些类型：

npm install --save-dev @types/web

方案2：手动声明URLSearchParams类型

如果不想新增依赖，可在项目中创建全局类型声明文件（比如src/types/global.d.ts），手动添加URLSearchParams的核心类型：

declare class URLSearchParams {
  constructor(init?: string | URLSearchParams | Record<string, string | string[]>);
  append(name: string, value: string): void;
  delete(name: string): void;
  entries(): Iterator<[string, string]>;
  forEach(callbackfn: (value: string, key: string, parent: URLSearchParams) => void, thisArg?: any): void;
  get(name: string): string | null;
  getAll(name: string): string[];
  has(name: string): boolean;
  keys(): Iterator<string>;
  set(name: string, value: string): void;
  sort(): void;
  toString(): string;
  values(): Iterator<string>;
  [Symbol.iterator](): Iterator<[string, string]>;
}

这个声明仅覆盖URLSearchParams的常用方法，不会引入多余环境类型，完全适配浏览器和Node.js v10+环境。

可选补充：运行时兼容性校验（非必需）

如果需要兼容极低版本环境，可添加简单的运行时判断：

function createSearchParams(init?: string | Record<string, string | string[]>) {
  if (typeof URLSearchParams === 'undefined') {
    throw new Error('当前环境不支持URLSearchParams，请升级至Node.js v10+或现代浏览器');
    // 也可引入qs等库做降级处理
    // import qs from 'qs';
    // return new URLSearchParams(qs.stringify(init));
  }
  return new URLSearchParams(init);
}