fetch 与 node-fetch 完整区别对比

一、基础定义

1. 浏览器原生 fetch 浏览器、Web Worker、前端环境自带的原生 API，无需安装第三方包，全局直接调用 fetch()。
2. node-fetch Node.js 早期版本没有内置 fetch，因此诞生的第三方 npm 包，专门在 Node 环境实现兼容浏览器标准的 fetch 接口。

二、核心环境差异（最关键）

表格

维度	浏览器原生 fetch	node-fetch
运行环境	浏览器、前端、WebWorker	Node.js 服务端（v17.5 前无内置）
安装依赖	无需安装，全局自带	Node < 18：必须 npm install node-fetch
内置状态	Node.js 18+ 已内置原生 fetch，不再需要 node-fetch	第三方库，现多用于老版本 Node 兼容
全局对象	挂载在 window /globalThis	需手动导入：import fetch from 'node-fetch'

补充：Node 版本分界线

• Node ≤ 17：无原生 fetch，只能用 node-fetch
• Node ≥ 18：内置标准 fetch（基于 undici），行为贴近浏览器，新项目不再需要 node-fetch

三、API 行为细微差异

1. 资源访问限制

• 浏览器 fetch 受同源策略 CORS限制，跨域请求会被浏览器拦截；不能访问本地文件系统。
• node-fetch（Node 环境） 无 CORS 限制，可自由请求任意域名；支持读取本地文件、内网、本地接口。

2. 请求头默认值不同

1. 浏览器 fetch 自动携带：Cookie、Origin、Referer，受浏览器缓存、Cookie 存储机制管理。
2. node-fetch 默认不带 Cookie、Origin、Referer，是无状态请求；需要手动配置 headers 或使用 CookieJar 实现会话保持。

3. 响应数据处理差异

1. 文本 / JSON 方法基本一致：res.text() / res.json()
2. 二进制流：
   • 浏览器：res.blob()、res.arrayBuffer()
   • node-fetch：额外支持 Node 特有 res.buffer() 返回 Buffer
3. 超时处理
   • 浏览器：使用 AbortController 标准方式
   • 旧版 node-fetch 额外提供 timeout 配置参数

4. 不支持浏览器特有 API

node-fetch 不存在这些浏览器专属对象：

• window、document
• FormData（旧版 node-fetch 需要额外导入）
• ReadableStream 实现略有区别

四、导入与使用示例

1. 浏览器原生 fetch（直接用）

// 前端页面直接全局调用
async function get() {
  const res = await fetch('https://api.example.com');
  const data = await res.json();
}

2. node-fetch（Node 17 及以下）

// ESM
import fetch from 'node-fetch';
// CommonJS
const fetch = require('node-fetch');

async function get() {
  const res = await fetch('https://api.example.com');
  const data = await res.json();
}

3. Node 18+ 原生 fetch（无需 node-fetch）

// Node 18+ 全局自带，无需安装包
const res = await fetch('https://api.example.com');

五、优缺点 & 适用场景

浏览器原生 fetch

✅ 优点：零依赖、标准规范、和前端环境完美适配、自动处理 Cookie/CORS

❌ 缺点：受跨域限制、只能在浏览器运行

node-fetch

✅ 优点：兼容低版本 Node、无跨域限制、服务端网络请求友好

❌ 缺点：需要额外安装、体积增加、需手动处理 Cookie、新项目已被 Node 内置 fetch 替代

六、总结选型建议

1. 前端浏览器项目：直接用原生 fetch，不要装 node-fetch
2. Node 18+ 后端项目：使用 Node 内置全局 fetch，移除 node-fetch 依赖
3. Node 16 及更低版本老项目：继续使用 node-fetch 做网络请求
4. 两者调用语法、Request/Response 规范完全一致，仅运行环境和底层限制不同，迁移成本极低。