Web API 是浏览器提供的接口而非 JavaScript 本身特性，由浏览器用 C++/Rust 实现并注入全局作用域；fetch、localStorage 等在 Node.js 中不可用，因无 DOM 和默认禁用；调用失败常因忽略 cookies 策略、存储限制、后台降频等约束；浏览器实现差异需查 caniuse 或特性检测。

Web API 不是 JavaScript 语言本身的一部分，而是浏览器提供的一套接口集合，JavaScript 通过它们才能真正与网页、用户、设备交互。不理解这点，就容易把 fetch、localStorage、addEventListener 当成“JS内置函数”，结果在 Node.js 环境里报错：ReferenceError: fetch is not defined。

Web API 和 JavaScript 引擎是两套东西

JavaScript 引擎（如 V8）只负责执行 JS 语法、处理对象、运行时等；而 document、setTimeout、navigator.geolocation 这些，都是浏览器用 C++/Rust 实现后“注入”到 JS 全局作用域的。Node.js 没有 DOM，所以 document 不存在；Deno 默认不暴露 localStorage，得手动启用 --location 才能用 localStorage。

常见 Web API 调用失败的三个典型原因

很多问题不是代码写错了，而是没搞清 Web API 的约束条件：

Java Api Extractor

从 Java 项目中提取 Controller 层接口定义为 JSON 数据。

下载

• fetch 默认不带 cookies，跨域请求需显式加 { credentials: 'include' }，否则后端收不到 session
• localStorage.setItem 存不下超过 5MB 的数据，且只能存字符串——存对象得先 JSON.stringify，取的时候漏了 JSON.parse 就是 “undefined”
• requestAnimationFrame 在页面被切换到后台标签页时会降频甚至暂停，不能用来做精确计时或动画帧同步

为什么有些 API 在 Chrome 里能用，Safari 却报错

不是所有 Web API 都已标准化，浏览器实现节奏不同：

• AbortSignal.timeout() 是较新的规范，Chrome 116+ 支持，Safari 17.4 才开始支持，旧版直接调用会报 TypeError: AbortSignal.timeout is not a function
• ResizeObserver 的 box 选项（控制观测边界盒类型）在 Firefox 中仍为实验性，设成 'border-box' 可能被忽略
• 使用前建议查 caniuse.com，或者用特性检测代替版本判断：if ('timeout' in AbortSignal) { ... }

真正难的不是记住 API 名字，而是每次调用前下意识问一句：这个 API 是谁提供的？它有没有隐含前提（比如必须在安全上下文、必须用户手势触发、是否跨域受限）？漏掉这些，debug 时就会反复卡在“明明文档写了，怎么就是不工作”。