大多数现代网络应用程序始终与服务器通信。 JavaScript Fetch API 是执行此操作的标准方法，它内置于浏览器和 Node.js 18 及更高版本中，因此无需安装任何内容。

基本使用需要两行，但许多教程就到此为止并忽略了导致真正错误的部分：故障处理。我们针对 Node.js 24 上的小型本地服务器测试了本指南中的示例，显示的输出来自该运行。代码中的 example.com 代表您自己的 API。如果 Promise 对您来说是新的，请从 JavaScript Promise 解释 开始。

什么是获取 API？

Fetch 是一个基于 Promise 的接口，用于发出 HTTP 请求。它取代了旧的、回调驱动的XMLHttpRequest，现在许多项目都使用它，而不是添加一个库来进行简单的调用。

GET 请求

Fetch 默认发出 GET 请求。有两个步骤，每个步骤都需要 await：首先响应标头到达，然后读取正文。

const response = await fetch("https://example.com/users/1");
const user = await response.json();

console.log(user);

// { id: 1, name: 'Asha' }

存在这两个步骤是因为正文可能很大并且比标头晚到达。在浏览器脚本中，顶级 await 需要一个模块，因此您通常会将其放入 async 函数中。请参阅我们的 JavaScript 异步/等待指南。

响应对象

在阅读正文之前，您可以检查响应：

console.log(response.status, response.ok, response.headers.get("content-type"));

// 200 true application/json

正文只能读取一次。在我们的测试中第二次调用 json() 失败：

await res.json();
await res.json();

// TypeError: Body is unusable: Body has already been read

如果您确实需要阅读两遍，请先调用response.clone()。

最大的惊喜：404 不会抛出异常

这是本文中最重要的事情。我们请求一个不存在的用户：

const res = await fetch("https://example.com/users/999");
console.log(res.status, res.ok);

// 404 false

没有抛出异常。就 fetch 而言，请求有效：已到达服务器并做出响应。仅当根本没有可用的响应到达时（例如网络故障），承诺才会拒绝。所以这样的代码有一个隐藏的错误：

try {
  const res = await fetch(url);
  const data = await res.json();   // may be an error payload
  showUser(data);                  // runs anyway for 404 and 500
} catch (error) {
  showError();                     // does not run for 404 or 500
}

查看我们的 HTTP 状态代码备忘单 以了解每个代码的含义。

可重复使用的帮手

不要到处重复该检查。缠绕一次：

async function getJson(url, options) {
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }
  return response.json();
}

try {
  await getJson("https://example.com/users/999");
} catch (error) {
  console.log("caught:", error.message);
}

// caught: Request failed with status 404

现在 HTTP 错误和网络错误都以相同的 catch 结束。这个小功能值得每个项目都拥有。真实版本还可能从响应正文中读取错误消息，并处理 204 No Content 响应，该响应没有要解析的 JSON。

POST JSON 数据

传递选项对象作为第二个参数。对于 JSON，您必须自己做两件事：将数据转换为字符串并设置标头。

const created = await getJson("https://example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ben" }),
});

console.log(created);

// { id: 2, name: 'Ben', type: 'application/json' }

我们的测试服务器回显收到的内容类型，确认标头已到达。忘记该标头是导致服务器错误的常见原因，因为许多框架仅在声明 JSON 时才对其进行解析。要上传表单或文件，请传递 FormData 对象作为正文，并不设置 Content-Type，因为浏览器需要自行添加边界值。

其他方法和选项

在 REST 和其他 API 风格之间进行选择？我们对 REST 与 GraphQL 的比较显示了 fetch 如何适合两者。

查询字符串

不要通过连接文本来构建查询字符串，因为特殊字符会破坏它们。 URLSearchParams 为您处理编码：

const params = new URLSearchParams({ q: "red shoes", page: 2 });
console.log(params.toString());

// q=red+shoes&page=2

await getJson(`https://example.com/search?${params}`);

// { q: 'red shoes', page: '2' }

服务器正确接收red shoes，空间恢复。

超时和取消

除非您另有说明，否则 Fetch 将在速度较慢的服务器上等待很长时间。 AbortSignal.timeout()设定了限制。我们的测试端点花费了两秒，而限制为 200 毫秒：

try {
  await fetch("https://example.com/slow", { signal: AbortSignal.timeout(200) });
} catch (error) {
  console.log(error.name);
}

// TimeoutError

要手动取消，例如当用户离开页面或键入新的搜索词时，请使用 AbortController：

const controller = new AbortController();
const pending = fetch("https://example.com/slow", { signal: controller.signal });

controller.abort();

try {
  await pending;
} catch (error) {
  console.log(error.name);
}

// AbortError

要一次运行多个请求，请使用 Promise.all，这比一次等待一个请求要快得多：

const [user, search] = await Promise.all([
  getJson("https://example.com/users/1"),
  getJson("https://example.com/search?q=a&page=1"),
]);

每一种失败

以下是我们运行中每次失败的情况，以及如何区分它们：

最后一行在生产中很常见。返回 502 的代理通常会发送 HTML 错误页面。我们复制了这个，并且 res.json() 抛出了 SyntaxError。在解析之前检查 response.ok 意味着您报告真正的问题，而不是令人困惑的解析错误。

CORS 和凭据

在浏览器中，从一个源到另一个源的请求受 CORS（跨源资源共享规则）的约束。如果您看到提及 Access-Control-Allow-Origin 的错误，则修复属于服务器，该服务器必须允许您的站点。在您的 JavaScript 中，故障仅显示为一般情况 TypeError，因此请查看浏览器控制台以了解实际原因。 Node.js 不强制实施 CORS，因此在脚本中有效的请求在浏览器中仍然可能会失败。

默认情况下，浏览器不会针对跨域请求发送 cookie。如果需要，请设置credentials: "include"，并确保服务器允许。切勿将秘密 API 密钥放入浏览器 JavaScript 中，因为任何人都可以读取它们。将它们保留在您的服务器上。

常见错误

• 不检查response.ok。错误响应被视为成功。
• 忘记第二个 await. response.json() 也会返回一个承诺。
• 忘记JSON.stringify。在正文发送[object Object]时传递对象。
• 将Content-Type设置为FormData.这会破坏边界，因此请将其保留。
• 没有超时。 挂起的请求可能会使页面的微调器无限期地运行。
• 解析 JSON 以获得空响应。 204 没有正文，json() 将抛出异常。

最后的话

一旦您记住其主要规则，Fetch 就很简单：响应并不等于成功。将小助手复制到您的项目中，添加超时并测试您的失败路径。下一步，构建一个小页面，从 API 加载数据，显示清晰的错误消息，并让用户取消缓慢的搜索。

常见问题

继续学习