node-fetch完全指南：10分钟上手Node.js Fetch API
项目地址: https://gitcode.com/gh_mirrors/no/node-fetch 你还在为Node.js中没有内置Fetch API而烦恼吗？还在纠结Axios和原生http模块的取舍吗？本文将带你10分钟快速掌握node-fetch，这个轻量级模块让你在Node.js环境中无缝使用浏览器同款Fetch API。读完本文后，你将能够：
- 掌握node-fetch的安装与基础使用
- 熟练发送GET、POST等各类HTTP请求
- 处理JSON、表单等不同类型的请求体
- 优雅处理错误和重定向
- 了解node-fetch与浏览器Fetch的核心差异
什么是node-fetch？
node-fetch是一个轻量级模块（package.json显示体积仅3.1.1版本），它将浏览器中的Fetch API（Fetch应用程序接口）引入到Node.js环境中。与传统的http模块相比，它提供了更现代、更简洁的Promise-based（基于承诺）API，让网络请求代码更易读、更易维护。
项目核心文件结构：
- 主入口：src/index.js
- 请求处理：src/request.js
- 响应处理：src/response.js
- 错误处理：src/errors/
快速开始：安装与基础使用
安装node-fetch
使用npm安装最新版node-fetch：
npm install node-fetch
或使用yarn：
yarn add node-fetch
第一个GET请求
node-fetch采用ES模块格式，因此需要使用import语法或require（需额外配置）。以下是一个简单的GET请求示例：
import fetch from 'node-fetch';
async function getExample() {
try {
const response = await fetch('https://api.example.com/data');
const data = await response.json();
console.log(data);
} catch (error) {
console.error('请求失败:', error);
}
}
getExample();
这段代码实现了三个核心步骤：
- 使用
fetch()发送请求并获取Response对象 - 调用
response.json()解析JSON响应体 - 使用try/catch捕获可能的错误
深入理解：核心功能与示例
发送JSON数据
发送JSON格式的POST请求是API交互中最常见的场景之一：
import fetch from 'node-fetch';
async function postJsonData() {
const data = {
name: 'node-fetch',
version: '3.1.1',
description: 'A light-weight module that brings Fetch API to node.js'
};
const response = await fetch('https://api.example.com/submit', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(data),
});
const result = await response.json();
console.log('提交结果:', result);
}
postJsonData();
处理表单数据
对于表单提交，可以使用FormData类（需要额外导入）：
import fetch from 'node-fetch';
import { FormData } from 'node-fetch';
async function submitForm() {
const form = new FormData();
form.append('username', 'testuser');
form.append('email', 'test@example.com');
// 添加文件（如果需要）
// form.append('avatar', fs.createReadStream('avatar.jpg'));
const response = await fetch('https://api.example.com/form', {
method: 'POST',
body: form
});
console.log(await response.text());
}
submitForm();
自定义请求选项
node-fetch支持丰富的请求选项，如设置请求头、超时、代理等：
const response = await fetch('https://api.example.com/data', {
method: 'GET', // 请求方法: GET, POST, PUT, DELETE等
headers: {
'Authorization': 'Bearer YOUR_TOKEN',
'User-Agent': 'node-fetch/3.1.1'
},
timeout: 5000, // 超时时间（毫秒）
compress: true, // 是否支持压缩
redirect: 'follow', // 重定向策略: follow, error, manual
follow: 10, // 最大重定向次数
agent: undefined // 自定义网络代理
});
错误处理与调试
node-fetch提供了完善的错误处理机制，主要通过FetchError类和AbortError类来实现：
async function fetchWithErrorHandling() {
try {
const response = await fetch('https://api.example.com/unstable-endpoint');
if (!response.ok) {
throw new Error(`HTTP错误! 状态码: ${response.status}`);
}
return await response.json();
} catch (error) {
if (error.type === 'aborted') {
console.error('请求已中止');
} else if (error.type === 'system') {
console.error('系统错误:', error.message);
} else if (error.type === 'invalid-json') {
console.error('JSON解析失败');
} else {
console.error('请求失败:', error.message);
}
}
}
请求中止（AbortController）
使用AbortController可以手动中止请求，这在处理超时或用户取消操作时非常有用：
import fetch from 'node-fetch';
async function fetchWithTimeout() {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 5000);
try {
const response = await fetch('https://api.example.com/slow-endpoint', {
signal: controller.signal
});
clearTimeout(timeoutId);
return await response.json();
} catch (error) {
if (error.name === 'AbortError') {
console.error('请求超时或已被中止');
}
}
}
node-fetch与浏览器Fetch的差异
虽然node-fetch尽力模拟浏览器Fetch API，但两者仍存在一些重要差异，详细内容可参考docs/v3-LIMITS.md：
| 特性 | 浏览器Fetch | node-fetch |
|---|---|---|
| 响应体 | ReadableStream | Node.js Readable Stream |
| 缓存 | 内置HTTP缓存 | 无内置缓存 |
| Cookie处理 | 自动处理 | 需要手动处理Set-Cookie头 |
| 重定向 | 自动跟随 | 可配置跟随策略 |
| 禁止的请求头 | 有（如Host, Origin等） | 无 |
| 流缓冲区大小 | 通常>1MB | 默认16KB（highWaterMark） |
处理流缓冲区差异
当克隆响应流时，node-fetch的缓冲区大小限制可能导致问题，解决方案是自定义highWaterMark：
const response = await fetch('https://example.com/large-file');
const clonedResponse = response.clone();
// 处理原始响应
response.body.pipe(process.stdout);
// 处理克隆响应（增加缓冲区大小）
const reader = clonedResponse.body.getReader({ highWaterMark: 1024 * 1024 });
高级用法与最佳实践
处理重定向
node-fetch提供了灵活的重定向处理机制，可通过redirect选项控制：
// 自动跟随重定向（默认行为）
fetch('https://example.com/redirect', { redirect: 'follow' });
// 手动处理重定向
fetch('https://example.com/redirect', { redirect: 'manual' })
.then(response => {
if (response.status >= 300 && response.status < 400) {
const redirectUrl = response.headers.get('Location');
console.log('重定向到:', redirectUrl);
// 手动处理重定向
return fetch(redirectUrl);
}
return response;
});
// 重定向时抛出错误
fetch('https://example.com/redirect', { redirect: 'error' })
.catch(error => {
console.error('遇到重定向:', error);
});
流式处理大文件
对于大文件下载，使用流式处理可以显著降低内存占用：
import fetch from 'node-fetch';
import { createWriteStream } from 'fs';
import { pipeline } from 'stream/promises';
async function downloadLargeFile() {
const response = await fetch('https://example.com/large-file.zip');
if (!response.ok) throw new Error(`HTTP错误: ${response.status}`);
await pipeline(
response.body,
createWriteStream('./large-file.zip')
);
console.log('文件下载完成');
}
downloadLargeFile();
总结与资源
node-fetch作为Node.js环境下的Fetch API实现，为开发者提供了现代化、Promise-based的网络请求方案。通过本文介绍，你已经掌握了其核心用法、错误处理和最佳实践。
官方资源：
- 完整文档：README.md
- 错误处理指南：docs/ERROR-HANDLING.md
- 升级指南：docs/v3-UPGRADE-GUIDE.md
- 限制说明：docs/v3-LIMITS.md
示例代码：example.js中包含了更多实用示例，涵盖了文本获取、JSON解析、POST请求等常见场景。
现在，你已经准备好在Node.js项目中充分利用node-fetch的强大功能了。无论是构建API客户端、数据爬虫还是微服务通信，node-fetch都能成为你的得力助手！
如果你觉得本文对你有帮助，请点赞、收藏并关注作者，获取更多Node.js开发技巧和最佳实践。下期我们将深入探讨node-fetch的高级特性和性能优化策略，敬请期待！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
