Next.js Commerce构建报Agent类型不兼容TypeScript错误如何解决

该报错是@vercel/fetch依赖的https-proxy-agent模块类型定义冲突导致：@vercel/fetch要求FetchOptions的agent属性仅支持Agent类型，但https-proxy-agent的类型定义包含了(parsedUrl: URL) => Agent的函数重载，二者类型不匹配触发了TypeScript校验报错，和业务代码逻辑无关。

• 最快临时规避：直接给fetch调用的第二个参数加类型断言，跳过当前位置的类型校验，修改第10行代码为：

const res = await fetch(config.commerceUrl, {
  ...fetchOptions,
  method: 'POST',
  headers: {
    ...fetchOptions?.headers,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query,
    variables,
  }),
} as Parameters<typeof fetch>[1])

如果觉得类型太宽松，也可以直接用as any断言，仅跳过本次校验不影响其他代码。

• 修正fetch导出类型：给./fetch.js新增同名类型声明文件./fetch.d.ts，覆盖@vercel/fetch自带的有问题的类型：

declare const fetch: typeof global.fetch
export default fetch

直接复用标准浏览器/Node.js内置fetch的类型定义，从根源避免类型冲突。

• 锁依赖版本：在package.json中强制锁定https-proxy-agent到无类型问题的兼容版本，不同包管理器配置如下：
  • npm/pnpm：在package.json新增overrides字段：

  {
    "overrides": {
      "https-proxy-agent": "^5.0.1"
    }
  }
  

  • yarn：在package.json新增resolutions字段：

  {
    "resolutions": {
      "https-proxy-agent": "^5.0.1"
    }
  }
  

  配置完成后重新安装依赖即可生效。
• 只有上述方案都无效时，才需要回溯所有调用fetchGraphqlApi的位置，检查是否手动传入了函数类型的agent参数，调整传入参数类型即可。

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