浏览器 Fetch receiver 陷阱：为什么网络错误可能发生在请求之前

8月 7, 2026

AI 参与说明：Agent：Codex；模型：当前运行环境未提供可核验的完整标识；reasoning effort：当前运行环境未提供可核验值。本文由 Codex 基于公开浏览器文档与已脱敏的通用故障模式整理，适用于浏览器端 TypeScript API 客户端，并按作者的明确发布指示公开。读者应结合文末一手资料和自身运行环境复核结论。

结论#

当一个浏览器 API Client 把原生 fetch 裸存为实例属性，再通过实例属性调用时，JavaScript 会把该实例作为函数的 this。某些浏览器实现会因此在请求发出之前抛出 Illegal invocation。如果客户端把这个异常笼统转换为“网络错误”，排障很容易错误地落在 CORS、网关、代理或后端。

默认的浏览器 fetch 应在取得时绑定到对应的全局对象；注入的自定义实现则应明确为“可独立调用的函数”。MDN 将 fetch() 记录为 Window 的方法，而 Function.prototype.bind() 的作用正是固定函数调用时的 this。

发生了什么#

下面这段代码看起来没有问题，但隐藏了调用接收者（receiver）的变化：

type FetchImplementation = typeof globalThis.fetch;

class ApiClient {
  private readonly fetchImplementation: FetchImplementation;

  constructor(options: { fetch?: FetchImplementation } = {}) {
    this.fetchImplementation = options.fetch ?? globalThis.fetch;
  }

  request(input: RequestInfo | URL, init?: RequestInit) {
    return this.fetchImplementation(input, init);
  }
}

this.fetchImplementation(input, init) 不是普通的裸函数调用。按照 JavaScript 的成员调用语义，函数看到的 this 是 ApiClient 实例，而不是浏览器的 Window 或 Worker 全局对象。对于不依赖 this 的普通 JavaScript 函数，这通常无影响；对于宿主提供的 Web API，实现可能要求正确的接收者，于是会同步抛出 TypeError: Illegal invocation。

这不是“所有浏览器、所有版本都会以同一种方式失败”的语言规范结论，而是应该被视为跨运行时客户端的兼容性风险：不要依赖宿主 API 在脱离原对象后仍能正常工作。

安全的客户端边界#

只绑定默认的原生实现，并把注入实现的约定写清楚：调用方提供的 fetch 必须已经能独立调用，不能是某个对象未绑定的方法。

type FetchImplementation = typeof globalThis.fetch;

class ApiClient {
  private readonly fetchImplementation: FetchImplementation;

  constructor(options: { fetch?: FetchImplementation } = {}) {
    this.fetchImplementation =
      options.fetch ?? globalThis.fetch.bind(globalThis);
  }

  request(input: RequestInfo | URL, init?: RequestInit) {
    const fetchImplementation = this.fetchImplementation;
    return fetchImplementation(input, init);
  }
}

这里不应对 options.fetch 再做 bind(globalThis)：自定义实现可能来自测试替身、观测包装器或另一运行时，强行替换它的接收者会引入新的行为变化。把默认实现绑定好、把注入函数的调用契约写清楚，边界更小也更容易测试。

不要把所有失败折叠为“网络错误”#

fetch() 的 Promise 不会因为 HTTP 404 或 500 自动 reject；这类响应需要检查 Response.ok 或 Response.status。相反，URL 无效、策略阻止、连接失败，以及调用 Web API 本身时抛出的异常都可能进入 catch。因此错误模型至少应保留“请求是否已经开始”的区别。

CORS 是浏览器对跨源脚本请求实施的 HTTP 头策略；带有非简单 header 的请求通常会产生 OPTIONS 预检，因此 Network 面板通常能提供预检或响应证据。MDN 的 CORS 指南适合用来核对这个链路。若调用栈已经在 fetch() 调用处失败且没有网络条目，先查调用语义，而不是先修改允许源名单。

ERR_BLOCKED_BY_CLIENT 也不等价于 CORS。Chromium 的网络错误清单将其定义为“客户端选择阻止请求”；它应作为浏览器环境的独立线索处理，而非直接推断为后端、域名或浏览器通用安全标准的问题。最可靠的做法是在另一个干净 profile 中复测，并结合 Network 的 Initiator、浏览器策略和本地请求规则缩小范围。

鉴权 API 的两个额外边界#

这类 receiver 问题与鉴权无关，但在修复请求层时，可以顺手把 API 的浏览器行为收紧：

await fetchImplementation(url, {
  headers: {
    Authorization: `Bearer ${token}`,
  },
  credentials: "omit",
  redirect: "error",
});

• credentials: "omit" 适用于 API 已明确以 Authorization bearer token 为凭证、且不应携带环境中 cookie 的场景。credentials 也会影响跨源请求的行为，应结合 RequestInit 文档 与服务端 CORS 规则设计。
• redirect: "error" 适用于不应进入交互式登录流程的机器 API。若请求被访问网关重定向到 HTML 登录页，客户端应得到可诊断错误，而不是跟随跳转后再把 HTML 当作 API 响应解析。它不适合本来就需要浏览器导航的登录接口。

两项设置都不是 receiver 错误的修复；它们只是在 API 契约已经确定时，避免把身份流程和数据 API 混在一起。

把回归测试放在调用约定上#

网络 mock 只能验证 URL、header 或响应体，未必能发现接收者错误。下面的 Vitest 例子专门断言默认 fetch 看到的是 globalThis。示例需要浏览器 API 可用的测试环境（例如 Node 18+ 的 Fetch 实现或浏览器测试环境）。

import { afterEach, describe, expect, it, vi } from "vitest";

type FetchImplementation = typeof globalThis.fetch;

class ApiClient {
  private readonly fetchImplementation: FetchImplementation;

  constructor(options: { fetch?: FetchImplementation } = {}) {
    this.fetchImplementation =
      options.fetch ?? globalThis.fetch.bind(globalThis);
  }

  request(input: RequestInfo | URL, init?: RequestInit) {
    const fetchImplementation = this.fetchImplementation;
    return fetchImplementation(input, init);
  }
}

afterEach(() => {
  vi.unstubAllGlobals();
});

describe("ApiClient", () => {
  it("calls the default fetch with globalThis as receiver", async () => {
    let receiver: unknown;

    vi.stubGlobal("fetch", function (this: unknown) {
      receiver = this;
      return Promise.resolve(new Response("{}"));
    });

    const client = new ApiClient();
    await client.request("https://example.test");

    expect(receiver).toBe(globalThis);
  });
});

这个测试没有访问真实网络，却能覆盖真正的回归点：默认全局 API 被缓存、包了一层、再从类方法调用时，接收者不能悄悄变成客户端对象。

一套更快的排障顺序#

1. 先在 DevTools Console 和 Network 同时观察：异常出现时是否已经生成请求条目。
2. 没有请求条目时，检查调用栈、URL 组装、fetch/XMLHttpRequest/WebSocket 的 receiver，以及 CSP。
3. 有预检或响应时，再依据状态码和 header 区分 CORS、网关跳转、鉴权和业务错误。
4. 对流式接口额外保留原始状态码、响应头、首个事件和解析异常，不要统一转换为“连接失败”。
5. 将确认过的调用约定写成单元测试；不要为了掩盖根因增加跨域代理、备用域名或多套鉴权 fallback。

最后一项尤其重要。浏览器客户端的兼容问题常常被“再加一层代理”暂时遮住，却让认证、可观测性和错误定位更复杂。优先采用平台和服务的官方 SDK、adapter 与文档化配置；只有确认官方路径无法覆盖时，再加入最小、隔离且带回归测试的适配层。

参考资料#

• MDN：Window.fetch()
• MDN：Function.prototype.bind()
• MDN：Cross-Origin Resource Sharing (CORS)
• MDN：RequestInit
• Chromium：网络错误清单
• WHATWG Fetch Standard