TypeScript使用node-fetch时HeadersInit添加自定义请求头编译报错解决

这几类报错的本质是对TypeScript联合类型属性访问规则的误解，同时代码本身存在运行时的隐藏逻辑缺陷：

• HeadersInit是三个独立类型的联合：Headers | string[][] | { [key: string]: string }，TypeScript默认仅当某类属性/索引访问方式对所有联合成员都合法时，才会通过类型检查，不会因为单个成员满足规则就放开全联合的访问权限。
• 对应两个具体报错的触发逻辑：
  • 报Property 'Authorization' does not exist on type 'Headers'：尝试直接给options.headers赋值.Authorization属性时，联合中的Headers类本身没有公开的可写Authorization实例属性——它的头信息存储在内部私有字段中，仅能通过set()/append()方法操作，该访问方式对Headers类型完全不合法，因此触发TS2339错误。
  • 报Element implicitly has an 'any' type ... Property 'User-Agent' does not exist on type 'HeadersInit'：尝试用字符串键'User-Agent'做索引访问时，联合中的Headers类没有字符串索引签名、string[][]是二维数组结构、不支持字符串键的对象读取，TS判断当前HeadersInit整体类型不支持该索引操作，因此触发TS7053隐式any错误。
• 需要明确一个运行时的隐藏bug：就算跳过类型检查，只要options.headers传入的是标准Headers类实例，直接给它挂载.Authorization属性的操作根本不会生效——fetch请求不会读取这些挂在实例上的自定义属性，最终发出的请求里不会带设置的授权头。
• 常见认知误区纠正：即使联合成员中包含一个带[key: string]: string索引签名的对象类型，也不代表可以对整个联合类型随意做字符串键的属性操作——TS不会单独为某一个联合成员的特性放开全联合的访问权限。

方案1：基于标准Headers类操作（最规范、无兼容问题） #

不管是浏览器原生fetch还是node-fetch，内部最终都会把入参的headers转成标准Headers类实例处理。直接基于Headers类的API操作，完全规避联合类型的属性访问问题，还能自动处理大小写不敏感、头去重等标准逻辑：

async function makeAuthorizedRequest(url: string, options: RequestInit) {
  // 用原始入参初始化标准Headers实例，构造函数原生支持所有HeadersInit格式
  const headers = new Headers(options?.headers ?? {});
  // 用Headers自带的set方法写入请求头，类型完全匹配
  headers.set('Authorization', `Bearer ${access_token}`);
  // 检查是否存在User-Agent请求头，不存在则补默认值
  if (!headers.has('User-Agent')) {
    headers.set('User-Agent', USERAGENT);
  }
  // 把处理好的Headers实例回传到请求配置中
  return fetch(url, {
    ...options,
    headers
  })
}

该方案的优势：

• 完全符合Web标准的Headers处理逻辑，运行时不会出现自定义头不生效的问题
• 类型检查100%通过，无强转、无ts-ignore
• 自动兼容所有入参headers格式，支持Headers实例、二维数组、普通对象三种入参形式

方案2：按需做类型收窄（适配需要操作纯对象headers的场景） #

如果业务逻辑中需要保留普通对象格式的headers（比如需要序列化headers做日志透传），就不能直接对联合类型的headers做属性访问，需要通过类型守卫把联合类型收窄到对应的成员类型，再执行属性操作：

async function makeAuthorizedRequest(url: string, options: RequestInit) {
  options ??= { headers: {} };
  // 通过类型守卫判断当前headers的具体类型
  if (
    !(options.headers instanceof Headers) &&
    !Array.isArray(options.headers)
  ) {
    // TS自动推断此处options.headers为普通对象格式，可直接做属性读写
    options.headers.Authorization = `Bearer ${access_token}`;
    if (!options.headers['User-Agent']) {
      options.headers['User-Agent'] = USERAGENT;
    }
  } else {
    // 对Headers实例、二维数组格式的headers，走标准Headers类的操作逻辑
    const headers = new Headers(options.headers);
    headers.set('Authorization', `Bearer ${access_token}`);
    if (!headers.has('User-Agent')) headers.set('User-Agent', USERAGENT);
    options.headers = headers;
  }
  return fetch(url, options);
}

• 不要将headers直接强转为any类型，会丢失所有类型保护，后续拼错请求头名称、写错头格式的问题都不会被TS提前发现。
• 不要混用“直接给对象加属性”和“操作Headers类实例”的写法，避免出现运行时头不生效的隐蔽问题。

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