跳到正文
零到全栈 · 卷 2 · 浏览器三件套

异步:fetch 与 Promise

本合集目录
本章目录

单册说明:本文件是卷 2 的第 6 章,可独立阅读。前置:第 5 章(DOM 与事件)。本章讲清"代码为什么不按你写的顺序执行",并用 fetch 把一份 JSON 读进页面。

项 内容
所属卷 卷 2 · 浏览器三件套(第 6 / 7 章)
前置章节 2.5 JS 与页面:DOM 与事件
本章产出 notes.json 示例数据 + bootstrap():首次打开时把示例数据导入 localStorage
对应代码 code/dudao/notes.json、code/dudao/index.html(第 6 章版本)
配图 无(后续统一制图)
读完的判定 能解释"为什么 fetch 拿到 404 却不进 catch",并写出一个带超时的请求

2.6.1 一句话结论:fetch 只在"没拿到响应"时才失败

先看一个几乎人人都踩过的现场。有人写了一个读取数据的函数:

async function loadNotes() {
  const res = await fetch('notes.json');
  const data = await res.json();
  return data;
}

loadNotes().then((data) => {
  console.log('读到了', data.length, '条');
});

他把 notes.json 改名成 notes-old.json,刷新页面,期待看到一段错误提示。结果是:

Uncaught (in promise) SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON

then 没有进 catch,res.ok 也不是 false 被检查出来的——报错发生在 res.json() 那一行,而且报的是"解析失败",不是"文件不存在"。

原因有两层。第一层:fetch 只要服务器返回了响应,哪怕状态码是 404、500,它都算"成功",Promise 会进入 fulfilled。第二层:本地服务器找不到文件时,返回的是一个 404 的 HTML 错误页,所以 res.json() 拿到的内容是 <!DOCTYPE html>...,解析当然失败。

这个设计的理由是:HTTP 层面"请求-响应"确实完成了,404 是一个合法的业务结果,不该被当成网络异常。但这个理由对使用者毫无帮助——它只意味着你必须自己检查 res.ok。

所以本章的两条主线:

一、异步代码不按书写顺序执行,理解事件循环才能预测顺序。 二、fetch 的失败分三种:网络层失败(进 catch)、HTTP 错误(要看 res.ok)、解析失败(在 res.json() 抛错)。

2.6.2 原理与方法

① 单线程与事件循环:为什么 setTimeout(fn, 0) 不是立刻

JavaScript 在浏览器里只有一个主线程执行你的代码。既然是单线程,就不能"同时"做两件事——那它怎么处理"等网络返回"这种耗时操作?

答案是把等待交给浏览器,自己先干别的。具体流程:

调用栈(执行你的代码)
   │ 空了?
   ▼
微任务队列(Promise 的回调)  ← 优先清空
   │ 空了?
   ▼
宏任务队列(setTimeout、事件、I/O)  ← 取一个执行
   │
   └──► 回到第一步

每一轮叫一个 tick。规则是:同步代码跑完 → 清空所有微任务 → 取一个宏任务 → 再清空微任务 → ……

console.log('1');

setTimeout(() => console.log('2'), 0);

Promise.resolve().then(() => console.log('3'));

console.log('4');

输出是 1 4 3 2。setTimeout 虽然写了 0 毫秒,它仍然要排队等当前同步代码跑完;而 Promise 的 then 是微任务,排在前面的宏任务之前。

概念 例子 谁先执行
同步代码 普通语句 最先,一路执行完
微任务 Promise.then、queueMicrotask、await 之后的代码 同步代码之后,立即清空
宏任务 setTimeout、setInterval、点击事件、fetch 的响应 微任务清空后,一次一个

所以 setTimeout(fn, 0) 的真实含义是"至少要等 0 毫秒,并且要排队"。规范允许的最小延迟是 4 毫秒(嵌套多层后);如果主线程正忙,它可能等几百毫秒。它从来不是"立刻",只是"尽快"。 任何依赖它精确计时的动画都会抖。

② 回调地狱:为什么需要 Promise

早期写法是把"下一步"塞进回调:

readNotes('notes.json', (err, notes) => {
  if (err) return handle(err);
  filterByTag(notes, '认知', (err2, filtered) => {
    if (err2) return handle(err2);
    countWords(filtered, (err3, stats) => {
      if (err3) return handle(err3);
      show(stats);
    });
  });
});

三个问题:错误处理重复三遍;缩进一层层往右;任何一步想加"重试"或"并行"都要重写。这叫回调地狱。

Promise 把"结果"变成一个对象,于是可以链式调用、可以组合、可以让错误沿着链条传递:

readNotes('notes.json')
  .then((notes) => filterByTag(notes, '认知'))
  .then((filtered) => countWords(filtered))
  .then((stats) => show(stats))
  .catch(handle);

③ Promise 三态:一旦落定,不可更改

状态 含义 能变成
pending 进行中 → fulfilled 或 rejected
fulfilled 成功,有一个值 不能再变
rejected 失败,有一个原因 不能再变

"不可变"这一条很重要:一个 Promise 被 reject 之后,你再调用 resolve 也不会有任何效果。所以同一个 Promise 可以被多个 then 订阅,它们拿到的是同一个结果。

方法 作用 返回
.then(onFulfilled, onRejected) 处理成功(第二个参数很少用) 新的 Promise
.catch(onRejected) 处理失败,等价于 .then(null, fn) 新的 Promise
.finally(fn) 不论成败都执行,不接收值 新的 Promise

.then 里 return 一个值,会被包成 fulfilled 的 Promise 传给下一个 .then;return 一个 Promise,会等它落定。这就是链式调用能"接力"的原理。

.catch 只捕获它之前的链条上的错误。写在最后的 .catch 能兜住前面所有环节——这也是为什么它通常放在链尾。.finally 适合做清理:关 loading、清定时器,它不改变链条的值。

④ async/await:把 Promise 写成同步的样子

async function loadNotes() {
  const res = await fetch('notes.json');
  const data = await res.json();
  return data;
}

await 的意思是"在这里暂停这个函数,等 Promise 落定,然后拿结果继续"。它不阻塞主线程——函数暂停的同时,主线程去跑别的东西了。所以它只是让代码"看起来"同步,执行仍然是异步的。

三个要点:

  1. async 函数永远返回 Promise。return data 会被包成 fulfilled 的 Promise。
  2. await 后面跟的不是 Promise 也没关系,会被包装一下。
  3. await 只能写在 async 函数里(顶层 await 在模块里可用,卷 3 会讲)。

错误处理用 try/catch:

async function loadNotes() {
  try {
    const res = await fetch('notes.json');
    if (!res.ok) {
      throw new Error(`请求失败:HTTP ${res.status}`);
    }
    return await res.json();
  } catch (err) {
    console.error('读取失败', err);
    return [];
  }
}

try/catch 能捕获 await 的 reject,是因为 await 在 Promise 被 reject 时会抛出那个原因。

⑤ 并发与串行:Promise.all 什么时候快得多

// 串行:一个接一个
const a = await fetchA();   // 300ms
const b = await fetchB();   // 300ms
const c = await fetchC();   // 300ms
// 总计约 900ms

// 并发:同时发出
const [a2, b2, c2] = await Promise.all([fetchA(), fetchB(), fetchC()]);
// 总计约 300ms
写法 总耗时 适用
顺序 await 各任务耗时之和 后一个依赖前一个的结果
Promise.all 最慢那个的耗时 任务互不依赖
Promise.allSettled 最慢那个的耗时 互不依赖,且允许部分失败

Promise.all 的行为要记住:只要有一个 reject,整体立刻 reject,其余结果被丢弃(但请求本身不会取消)。如果你的场景是"三个都要试,失败一个不影响其他",用 Promise.allSettled,它返回 [{status, value|reason}]。

还有一个高频错误:在 forEach 里 await。

// 错的:forEach 不会等,三个请求同时发出且没人等结果
items.forEach(async (item) => {
  await save(item);
});

// 对的:用 for...of,真串行
for (const item of items) {
  await save(item);
}

因为 forEach 的回调是普通函数,await 只暂停那个回调自己,forEach 本身立刻返回。

⑥ fetch 的三种失败,必须分开处理

失败类型 表现 怎么判断
网络层失败 DNS 解析不了、断网、跨域被拦、请求被中止 Promise reject,进 catch
HTTP 错误 404、500、403 Promise 成功,看 res.ok === false 或 res.status
解析失败 返回的不是 JSON res.json() 抛 SyntaxError

所以完整的读取逻辑长这样,三层都要有:

async function loadJson(url) {
  let res;
  try {
    res = await fetch(url);
  } catch (err) {
    throw new Error(`网络层失败:${err.message}`);
  }

  if (!res.ok) {
    throw new Error(`HTTP ${res.status}:${url}`);
  }

  try {
    return await res.json();
  } catch (err) {
    throw new Error(`返回的不是合法 JSON:${url}`);
  }
}

⑦ 超时:fetch 自己没有超时

fetch 没有 timeout 参数。网络卡住时,它会一直等下去(浏览器最终会有自己的上限,可能几分钟)。要控制超时,用 AbortController:

async function fetchWithTimeout(url, ms) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), ms);
  try {
    const res = await fetch(url, { signal: controller.signal });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.json();
  } finally {
    clearTimeout(timer);
  }
}

被中止时,fetch 抛出的错误 name 是 AbortError,消息是 The user aborted a request.。注意 finally 里的 clearTimeout 必须写:请求正常返回后如果不清理,那个定时器还会在几秒后触发一次 abort(),虽然对已完成的请求没影响,但会留下无意义的定时器。

2.6.3 动手:从 file:// 失败到 http:// 成功

第一步:造一份数据

在 index.html 同目录下新建 notes.json,内容如下(整段复制,包括方括号):

[
  {
    "id": 1794880800000,
    "title": "注意力是稀缺资源",
    "content": "把注意力当成预算来花,而不是当成免费的空气。",
    "sourceUrl": "https://reading.example/2026/11/attention",
    "tags": ["认知", "写作"],
    "createdAt": "2026-11-17T02:00:00.000Z"
  },
  {
    "id": 1794794400000,
    "title": "先写,再改",
    "content": "初稿的唯一任务是存在,不是正确。写作的注意力应该放在把想法倒出来。",
    "sourceUrl": "https://reading.example/2026/11/draft",
    "tags": ["写作"],
    "createdAt": "2026-11-16T02:00:00.000Z"
  },
  {
    "id": 1794708000000,
    "title": "笔记的价值在连接",
    "content": "一条孤立的摘录价值很低,它和别的摘录连起来才有价值。所以标签比正文更重要。",
    "sourceUrl": "https://reading.example/2026/11/link",
    "tags": ["认知"],
    "createdAt": "2026-11-15T02:00:00.000Z"
  }
]

第二步:先制造失败(重要)

在 index.html 的 </body> 前,把第 5 章最后两行:

notes = loadNotes();
render('');

替换成:

async function loadSeed() {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 5000);

  try {
    const res = await fetch('notes.json', { signal: controller.signal });
    if (!res.ok) {
      throw new Error(`读取示例数据失败:HTTP ${res.status}`);
    }
    const seed = await res.json();
    return Array.isArray(seed) ? seed : [];
  } finally {
    clearTimeout(timer);
  }
}

async function bootstrap() {
  notes = loadNotes();

  if (notes.length === 0) {
    try {
      notes = await loadSeed();
      saveNotes();
    } catch (err) {
      console.warn('没读到示例数据,从空列表开始', err);
    }
  }

  render('');
}

bootstrap();

现在直接双击 index.html,用 file:// 打开。打开控制台,你会看到这一行(路径随你的目录变化):

Access to fetch at 'file:///C:/code/dudao/notes.json' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: http, https, data, ...

冒号后面那串协议名单在不同浏览器版本里顺序和内容都不一样,不必逐字对齐。抓住两个关键词就够了:blocked by CORS policy 和 origin 'null'。 看到它们,结论只有一个——你正在用 file:// 打开页面。

紧接着还有一行 Failed to load resource: net::ERR_FAILED,以及你自己打的那句警告:没读到示例数据,从空列表开始。

这就是本章唯一需要你亲眼看到的失败。它不是"文件不存在"——文件就在那里。是浏览器拒绝让 file:// 页面去读另一个文件。原因在第 7 章会展开:file:// 的源(origin)是 null,浏览器认为"来源不明的页面不该读本地文件",这个策略叫同源策略。

注意这一段的设计:catch 只打了一句警告,页面照常渲染空列表。这是故意的——示例数据读不到不是致命错误,用户还能手填。生产代码里,"可选数据的加载失败"永远不该让整个页面白屏。

第三步:起一个本地服务

在 index.html 所在目录打开终端:

cd C:/code/dudao
python -m http.server 8000

看到 Serving HTTP on :: port 8000 ...,然后在浏览器打开:

http://127.0.0.1:8000/

刷新。这次列表里有三条摘录,关键词区也有了词条。终端里会打出两行访问记录:一行 GET /,一行 GET /notes.json(可能还会多一条 favicon.ico 的 404——浏览器自动来要网站图标,与你的代码无关,第 7 章会讲怎么处理)。

如果之前已经手动存过数据,localStorage 不为空,bootstrap 会跳过导入。想重新看导入效果,先在控制台执行 localStorage.removeItem('dudao.notes.v1') 再刷新。

第四步:验证 404 不报错

把地址改成 http://127.0.0.1:8000/missing.json,在控制台执行:

const res = await fetch('missing.json');
console.log(res.status, res.ok, res.headers.get('content-type'));

输出是 404 false text/html(python -m http.server 返回的是 HTML 错误页)。没有任何红字,Promise 是成功的。 这就是"fetch 不因 404 抛错"的实证。

再执行:

await fetch('missing.json').then((r) => r.json());

这一行才会报错:SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON。三层失败在同一个请求上依次出现,这是本章最值得记住的一组现象。

第五步:验证超时

const controller = new AbortController();
setTimeout(() => controller.abort(), 1);
try {
  await fetch('notes.json', { signal: controller.signal });
} catch (err) {
  console.log(err.name, err.message);   // AbortError  The user aborted a request.
}

把 1 毫秒的延迟改成 0,可能请求已经完成,就看不到报错——这正说明"超时控制是和时间赛跑",1 毫秒本身不可靠。真实项目里给 5–10 秒比较合理。

2.6.4 三个坑

坑 1:fetch 拿到 404,代码却当成成功

症状:接口挂了,页面显示一片空白或者 undefined,但控制台没有红字,catch 也没进。

成因:fetch 只在网络层失败(断网、跨域、被中止)时 reject。404、500 都是"服务器正常回应了",Promise 进入 fulfilled。接着 res.json() 解析 HTML 错误页,抛的是 SyntaxError,很多人根本没包这一段。

修法:每个 await fetch(...) 后面紧跟一句 if (!res.ok) throw new Error(...)。把这一句当成肌肉记忆,就像写完 if 就补花括号一样。

坑 2:忘写 await,拿到一个 Promise

症状:console.log(data) 打印出 Promise {<pending>};或者 data.length 是 undefined;或者页面显示 [object Promise]。

成因:fetch、res.json()、任何 async 函数都返回 Promise。少写一个 await,你拿到的是"未来会有结果"的凭证,不是结果本身。

修法:在 async 函数里,凡是返回 Promise 的调用都加 await;写完之后把每个 await 的下游类型在脑子里过一遍。Promise {<pending>} 这个输出本身就是最明确的提示——看到它就往上游找漏掉的 await。

坑 3:在 forEach 里 await,循环没等就结束了

症状:批量保存十条数据,日志显示"全部完成"时数据库里只有两三条;或者后面的代码用到了还没写入的数据。

成因:forEach 的回调是独立函数,await 只暂停那一个回调。forEach 本身不返回 Promise,也不等任何人,立刻返回。

修法:需要顺序执行用 for (const item of items) { await save(item); };需要并发且要等全部完成,用 await Promise.all(items.map((item) => save(item)))。map 能返回 Promise 数组,forEach 返回 undefined——这是两者的关键差别。


本章验收

  • 双击 index.html 时能在控制台看到 blocked by CORS policy 的完整报错
  • python -m http.server 8000 之后,页面自动导入三条示例数据
  • 能在控制台用 fetch 复现"404 不抛错"和"res.json() 抛 SyntaxError"
  • 能说出同步代码、微任务、宏任务的执行顺序,并预测 1 4 3 2 那个例子
  • 能写出带 AbortController 的超时请求,并说出为什么要 clearTimeout
  • 能解释为什么 forEach 里 await 不起作用

自测

Q1:fetch('x.json') 返回 500,且响应体是合法 JSON {"error":"boom"}。await res.json() 会抛错吗?

看答案 不会。500 只影响 `res.ok`(为 `false`)和 `res.status`,不影响响应体解析。只要响应体是合法 JSON,`res.json()` 就正常返回 `{error: 'boom'}`。所以"HTTP 错误"必须靠 `res.ok` 判断,不能指望 `json()` 抛错。反过来说,如果服务器返回的是 HTML 错误页,`json()` 才会抛 `SyntaxError`——那时你连真正的错误信息都拿不到。

Q2:下面这段代码输出什么顺序?为什么?

setTimeout(() => console.log('A'), 0);
Promise.resolve().then(() => console.log('B'));
console.log('C');
看答案 `C B A`。`console.log('C')` 是同步代码,最先执行。同步代码跑完后,事件循环先清空微任务队列,`then` 的回调(B)是微任务,所以第二个。最后才取宏任务,`setTimeout` 的回调(A)第三。这就是"微任务优先于宏任务",也是 `await` 之后代码总在当前同步代码之后执行的原因。

Q3:为什么 Promise.all([a(), b(), c()]) 比三个顺序 await 快?如果 b() 失败了呢?

看答案 顺序 `await` 是串行的:发出 a 的请求后等它完成,再发 b,再等,总耗时是三者之和。`Promise.all` 里三个函数**先被调用**,请求同时发出,然后一起等,总耗时约等于最慢那个。如果 `b()` reject,`Promise.all` 立刻整体 reject,a 和 c 的结果被丢弃(但它们的请求不会被取消,仍会跑完)。如果要拿到全部结果(包括失败的那个),用 `Promise.allSettled`。

下一步

到这里,代码全挤在一个 index.html 里:HTML、CSS、JS 混在一起,已经六百多行。下一章把它拆成三个文件——你会立刻撞上三类报错,而它们长得几乎一样。

→ 卷2-07-拆成三个文件然后撞墙.md