# make-fetch-happen 中文文档

规范地址：https://npmcn.com/package/make-fetch-happen/

版本：16\.0\.1
npm 元数据更新时间：2026-09-09T20:11:02.325Z
中文译文更新时间：2026-11-05T16:47:01.189Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/make-fetch-happen
原文对照：https://npmcn.com/package/make-fetch-happen/?lang=original
项目主页：https://github.com/npm/make-fetch-happen#readme
源码仓库：https://github.com/npm/make-fetch-happen

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：53.2 kB，13 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：^22\.22\.2 \|\| ^24\.15\.0 \|\| \>=26\.0\.0
- 运行依赖：12 个
- 首次发布：2017-03-27T23:41:48.082Z
- 最新版本发布：2026-05-26T17:46:02.384Z
- 近 30 天下载量：122004087（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：119（近 12 个月 6 个）

## 中文简介

观察、 缓存、 重试抓取客户端

## 安装

```sh
npm install make-fetch-happen
```

也可以使用：`pnpm add make-fetch-happen`、`yarn add make-fetch-happen`、`bun add make-fetch-happen`

## README

# 调制相机

[![npm version](https://img.shields.io/npm/v/make-fetch-happen.svg)](https://npm.im/make-fetch-happen) [![license](https://img.shields.io/npm/l/make-fetch-happen.svg)](https://npm.im/make-fetch-happen) [![Coverage Status](https://coveralls.io/repos/github/npm/make-fetch-happen/badge.svg?branch=latest)](https://coveralls.io/github/npm/make-fetch-happen?branch=latest)

[`make-fetch-happen`](https://github.com/npm/make-fetch-happen) 是节点.js 书目 [`minipass-fetch`](https://github.com/npm/minipass-fetch) 包含额外 特性 [`minipass-fetch`](https://github.com/npm/minipass-fetch) 不包括 HTTP 缓存支持请求 集合,代理,重复, [更多](https://npmcn.com/package/make-fetch-happen/#readme-features)来啊!

## 安装

`$ npm install --save make-fetch-happen`

## 目录

-   [示例](https://npmcn.com/package/make-fetch-happen/#readme-example)
-   [特征](https://npmcn.com/package/make-fetch-happen/#readme-features)
-   [捐款](https://npmcn.com/package/make-fetch-happen/#readme-contributing)
-   [API 密码](https://npmcn.com/package/make-fetch-happen/#readme-api)
    -   [`fetch`](https://npmcn.com/package/make-fetch-happen/#readme-fetch)
    -   [`fetch.defaults`](https://npmcn.com/package/make-fetch-happen/#readme-fetch-defaults)
    -   [`minipass-fetch` 选项](https://npmcn.com/package/make-fetch-happen/#readme-minipass-fetch-options)
    -   [`make-fetch-happen` 选项](https://npmcn.com/package/make-fetch-happen/#readme-extra-options)
        -   [`opts.cachePath`](https://npmcn.com/package/make-fetch-happen/#readme-opts-cache-path)
        -   [`opts.cache`](https://npmcn.com/package/make-fetch-happen/#readme-opts-cache)
        -   [`opts.cacheAdditionalHeaders`](https://npmcn.com/package/make-fetch-happen/#readme-opts-cache-additional-headers)
        -   [`opts.proxy`](https://npmcn.com/package/make-fetch-happen/#readme-opts-proxy)
        -   [`opts.noProxy`](https://npmcn.com/package/make-fetch-happen/#readme-opts-no-proxy)
        -   [`opts.ca, opts.cert, opts.key`](https://npmcn.com/package/make-fetch-happen/#readme-https-opts)
        -   [`opts.maxSockets`](https://npmcn.com/package/make-fetch-happen/#readme-opts-max-sockets)
        -   [`opts.retry`](https://npmcn.com/package/make-fetch-happen/#readme-opts-retry)
        -   [`opts.onRetry`](https://npmcn.com/package/make-fetch-happen/#readme-opts-onretry)
        -   [`opts.integrity`](https://npmcn.com/package/make-fetch-happen/#readme-opts-integrity)
        -   [`opts.dns`](https://npmcn.com/package/make-fetch-happen/#readme-opts-dns)
-   [我们赞助者发来的消息](https://npmcn.com/package/make-fetch-happen/#readme-wow)

### 示例

```javascript
const fetch = require('make-fetch-happen').defaults({
  cachePath: './my-cache' // path where cache will be written (and read)
})

fetch('https://registry.npmjs.org/make-fetch-happen').then(res => {
  return res.json() // download the body as JSON
}).then(body => {
  console.log(`got ${body.name} from web`)
  return fetch('https://registry.npmjs.org/make-fetch-happen', {
    cache: 'no-cache' // forces a conditional request
  })
}).then(res => {
  console.log(res.status) // 304! cache validated!
  return res.json().then(body => {
    console.log(`got ${body.name} from cache`)
  })
})
```

### 特征

-   围绕 [`minipass-fetch`](https://npm.im/minipass-fetch) 核心项目 [`fetch` API 密码](https://fetch.spec.whatwg.org/) 执行
-   请求集合出框
-   相当快,真的
-   自动重试 HTTP 语义感知请求
-   缓存返回自动“ 离线模式”
-   根据 HTTP 缓存规则新建请求缓存(`Cache-Control`, (中文(简体) ), `ETag`, (中文(简体) ), `304`s, 缓存倒计时出错等).
-   节点.js流支持
-   透明 gzip 并调高支持
-   [分资源](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) 支助
-   代理支持(https, https, socks, socks4, socks5. 通过 [`@npmcli/agent`](https://npm.im/@npmcli/agent)(中文(简体) )
-   DNS 缓存( 通过 (通过)[`@npmcli/agent`](https://npm.im/@npmcli/agent)(中文(简体) )

#### `> fetch(uriOrRequest, [opts]) -> Promise<Response>`

此函数执行大多数 [`fetch` API 密码](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch): 给定 `uri` 字符串或一个 `Request` 例如,它将发射一个http请求,并返回包含相关响应的保证.

若为 `opts` 提供 [`minipass-fetch`\- 具体选项](https://npmcn.com/package/make-fetch-happen/#readme-minipass-fetch-options) 将会被传递到图书馆。 还有 [额外选项](https://npmcn.com/package/make-fetch-happen/#readme-extra-options) 指定用于添加各种特性的 make-fetch-happen,例如 HTTP 缓存、完整性验证、代理支持等等.

##### 示例

```javascript
fetch('https://google.com').then(res => res.buffer())
```

#### `> fetch.defaults([defaultUrl], [defaultOpts])`

返回一个新的 `fetch` 函数将调用 `make-fetch-happen` 使用 `defaultUrl` 财务报告和审定财务报表 `defaultOpts` 作为任何呼叫的默认值.

默认 `fetch` 还将有一个 `.defaults()` 方法,所以它们可以被链.

##### 示例

```javascript
const fetch = require('make-fetch-happen').defaults({
  cachePath: './my-local-cache'
})

fetch('https://registry.npmjs.org/make-fetch-happen') // will always use the cache
```

#### `> minipass-fetch options`

以下备选方案: `minipass-fetch` 用作:

-   方法
-   机构
-   重定向
-   跟着
-   超时
-   压缩
-   大小

这些其他选项通过 make-fach-happen 修改或扩充 :

-   信头 - 默认 `User-Agent` 设作相会. `Connection` 设置为 `keep-alive` 或者说 `close` 自动取决于 `opts.agent`。 。 。 .

详情见 [文档 `minipass-fetch` 本身](https://github.com/npm/minipass-fetch#options)。 。 。 .

#### `> make-fetch-happen options`

make-fetch-appen 将增加 `minipass-fetch` API通过额外选项提供附加功能. 可供选择的其他方案如下:

-   [`opts.cachePath`](https://npmcn.com/package/make-fetch-happen/#readme-opts-cache-path) - 要读取/写入缓存目标
-   [`opts.cache`](https://npmcn.com/package/make-fetch-happen/#readme-opts-cache) - 说吧 `fetch` 缓存模式 。 控制缓存 _行为_。 。 。 .
-   [`opts.cacheAdditionalHeaders`](https://npmcn.com/package/make-fetch-happen/#readme-opts-cache-additional-headers) - 在缓存中存储额外的信头
-   [`opts.proxy`](https://npmcn.com/package/make-fetch-happen/#readme-opts-proxy) - 代理代理人
-   [`opts.noProxy`](https://npmcn.com/package/make-fetch-happen/#readme-opts-no-proxy) - 要禁用代理部件 .
-   [`opts.ca, opts.cert, opts.key, opts.strictSSL`](https://npmcn.com/package/make-fetch-happen/#readme-https-opts)
-   [`opts.localAddress`](https://npmcn.com/package/make-fetch-happen/#readme-opts-local-address)
-   [`opts.maxSockets`](https://npmcn.com/package/make-fetch-happen/#readme-opts-max-sockets)
-   [`opts.retry`](https://npmcn.com/package/make-fetch-happen/#readme-opts-retry) - 请求重试设置
-   [`opts.onRetry`](https://npmcn.com/package/make-fetch-happen/#readme-opts-onretry) - 尝试重试时称为函数
-   [`opts.integrity`](https://npmcn.com/package/make-fetch-happen/#readme-opts-integrity) - 说吧 [分资源](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) 元数据.
-   [`opts.dns`](https://npmcn.com/package/make-fetch-happen/#readme-opts-dns) - DNS 缓存选项
-   [`opts.agent`](https://npmcn.com/package/make-fetch-happen/#readme-opts-agent) - http/https/proxy/socks代理选项。 见 [`@npmcli/agent`](https://npm.im/@npmcli/agent) 需要更多信息.

#### `> opts.cachePath`

字符串 `Path` 用作缓存根 [`cacache`](https://npm.im/cacache)。 。 。 .

**页:1**: 请求不会被缓存,除非其反应机构被消耗. 您需要使用一个 `res.json()`, (中文(简体) ), `res.buffer()`等反应方法,或 `res.body` 流出,以便被写出.

默认缓存管理器在缓存回复中也添加了以下信头:

-   `X-Local-Cache`: 缓存路径, 内容被发现于
-   `X-Local-Cache-Key`: 此响应的唯一缓存条目密钥
-   `X-Local-Cache-Mode`: 永远 `stream` 说明如何从cacache读取答复
-   `X-Local-Cache-Hash`: 缓存条目的特定完整性散列
-   `X-Local-Cache-Status`: 一个 `miss`, (中文(简体) ), `hit`, (中文(简体) ), `stale`, (中文(简体) ), `revalidated`, (中文(简体) ), `updated`,或 `skip` 以显示反应是如何创建的
-   `X-Local-Cache-Time`: 输入的缓存插入时间的 UTCString

使用 [`cacache`](https://npm.im/cacache)这样的电话可能会用来 手动获取缓存条目 :

```javascript
const h = response.headers
cacache.get(h.get('x-local-cache'), h.get('x-local-cache-key'))

// grab content only, directly:
cacache.get.byDigest(h.get('x-local-cache'), h.get('x-local-cache-hash'))
```

##### 示例

```javascript
fetch('https://registry.npmjs.org/make-fetch-happen', {
  cachePath: './my-local-cache'
}) // -> 200-level response will be written to disk
```

#### `> opts.cache`

此选项遵循标准 `fetch` API 缓存选项 。 如果 [`opts.cachePath`](https://npmcn.com/package/make-fetch-happen/#readme-opts-cache-path) 无效。 下列值被接受(作为字符串):

-   `default` - 获取会检查HTTP缓存 在去网络的路上。 如果有新的反应,它将被使用。 如果有呆滞的答复,将生成一个有条件的请求,而正常的请求则另作选择。 它随后以响应更新了HTTP缓存. 如果重新验证请求失败(例如500上下线或下线时),则会返回已失效的响应.
-   `no-store` - 获取行为就像根本没有 HTTP 缓存.
-   `reload` - 获取行为, 仿佛在网络路上没有 HTTP 缓存 。 Ergo,它创建了普通请求并用响应更新了HTTP缓存.
-   `no-cache` - 如果在 HTTP 缓存中存在响应和普通请求, 获取创建有条件请求 。 它随后以响应更新了HTTP缓存.
-   `force-cache` - 获取使用匹配请求的 HTTP 缓存中的任何响应,而不注意 Staleity 。 如果没有响应,它会创建一个正常的请求,并用响应来更新HTTP缓存.
-   `only-if-cached` - 获取使用匹配请求的 HTTP 缓存中的任何响应,而不注意 Staleity 。 如果没有响应,它会返回一个网络错误. (只有在请求模式是“同源”时才能使用)。 任何缓存重定向都会被遵循,假设请求的重定向模式是"遵循",重定向不会违反请求模式. )

(注:选项说明取自 [https://fetch.spec.whywg.org/#http-network-or-cache-fetch 页面存档备份,存于互联网档案馆](https://fetch.spec.whatwg.org/#http-network-or-cache-fetch)(中文(简体) )

##### 示例

```javascript
const fetch = require('make-fetch-happen').defaults({
  cachePath: './my-cache'
})

// Will error with ENOTCACHED if we haven't already cached this url
fetch('https://registry.npmjs.org/make-fetch-happen', {
  cache: 'only-if-cached'
})

// Will refresh any local content and cache the new response
fetch('https://registry.npmjs.org/make-fetch-happen', {
  cache: 'reload'
})

// Will use any local data, even if stale. Otherwise, will hit network.
fetch('https://registry.npmjs.org/make-fetch-happen', {
  cache: 'force-cache'
})
```

#### `> opts.cacheAdditionalHeaders`

下列信头在出现时总是被存储在缓存中:

-   `cache-control`
-   `content-encoding`
-   `content-language`
-   `content-type`
-   `date`
-   `etag`
-   `expires`
-   `last-modified`
-   `link`
-   `location`
-   `pragma`
-   `vary`

此选项允许用户在缓存中存储额外的自定义头.

##### 示例

```javascript
fetch('https://registry.npmjs.org/make-fetch-happen', {
  cacheAdditionalHeaders: ['my-custom-header'],
})
```

#### `> opts.proxy`

字符串或 `new url.URL()`\-URI通过代理 不同的代理处理器将 根据代理协议使用.

此外, `process.env.HTTP_PROXY`, (中文(简体) ), `process.env.HTTPS_PROXY`,以及 `process.env.PROXY` 如果有,则使用 `opts.proxy` 提供了数值.

(待定) `process.env.NO_PROXY` 也可以配置为跳过所有域或特定域的代理请求.

##### 示例

```javascript
fetch('https://registry.npmjs.org/make-fetch-happen', {
  proxy: 'https://corporate.yourcompany.proxy:4445'
})

fetch('https://registry.npmjs.org/make-fetch-happen', {
  proxy: {
    protocol: 'https:',
    hostname: 'corporate.yourcompany.proxy',
    port: 4445
  }
})
```

#### `> opts.noProxy`

如果存在, 应该是逗号分隔的字符串或域扩展名的数组 代理应该 _没有_ 用于.

此选项也可通过下列方式提供: `process.env.NO_PROXY`。 。 。 .

#### `> opts.ca, opts.cert, opts.key, opts.strictSSL`

这些值直接传递给 HTTPS 代理,并将用于两者 代理和未代理的 HTTPS 请求 。 它们大多与 相同选项 `https` 模块接受,它们本身将传递给 `tls.connect()`。 。 。 . `opts.strictSSL` 对应于 `rejectUnauthorized`。 。 。 .

#### `> opts.localAddress`

直接传给 `http` 财务报告和审定财务报表 `https` 请求呼叫。 决定本地 地址将绑定.

#### `> opts.maxSockets`

默认: 15

用于基础活动的并行套接字的最大数量 Http/Https/Proxy 剂. 此设定适用于每个产卵剂一次.

十五岁大概是 _价值相当高_ 用于大多数用例,平衡速度 与,呃,不敲人路由器

#### `> opts.retry`

一个可用于调制请求重试设置的对象. 只有在下列条件下才会试图收回:

-   请求方法为 NOT `POST` 和
-   申请地位包括: `408`, (中文(简体) ), `420`, (中文(简体) ), `429`,或者任何状态 在500范围。 或
-   请求错误 `ECONNRESET`, (中文(简体) ), `ECONNREFUSED`, (中文(简体) ), `EADDRINUSE`, (中文(简体) ), `ETIMEDOUT`,或 `fetch` 错误 `request-timeout`。 。 。 .

值得指出的是,以下是明确未重审的:

-   `getaddrinfo ENOTFOUND` 并被假定为无法访问的域名,或者用户会被假定为离线。 如果一个响应被缓存, 将立即返回 .

若为 `opts.retry` 实值 `false`,相当于 `{retries: 0}`

若为 `opts.retry` 是一个数字,它相当于 `{retries: num}`

如果您想要对它进行更多的控制, 可以重试以下选项 :

-   重试
-   因素
-   分钟超时
-   最大超时
-   随机

详细情况请参见: [`retry`](https://npm.im/retry) 文档.

##### 示例

```javascript
fetch('https://flaky.site.com', {
  retry: {
    retries: 10,
    randomize: true
  }
})

fetch('http://reliable.site.com', {
  retry: false
})

fetch('http://one-more.site.com', {
  retry: 3
})
```

#### `> opts.onRetry`

当尝试重试时, 使用导致重试的响应或错误调用函数 .

##### 示例

```javascript
fetch('https://flaky.site.com', {
  onRetry(cause) {
    console.log('we will retry because of', cause)
  }
})
```

#### `> opts.integrity`

匹配对应给定的响应正文 [分资源](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) 元数据。 如果校验失败, 请求将失败 `EINTEGRITY` 错误.

`integrity` 可能是一个字符串或 [`ssri`](https://npm.im/ssri) `Integrity`\- 喜欢.

##### 示例

```javascript
fetch('https://registry.npmjs.org/make-fetch-happen/-/make-fetch-happen-1.0.0.tgz', {
  integrity: 'sha1-o47j7zAYnedYFn1dF/fR9OV3z8Q='
}) // -> ok

fetch('https://malicious-registry.org/make-fetch-happen/-/make-fetch-happen-1.0.0.tgz', {
  integrity: 'sha1-o47j7zAYnedYFn1dF/fR9OV3z8Q='
}) // Error: EINTEGRITY
```

## 常见问题

### make-fetch-happen 是什么？

观察、 缓存、 重试抓取客户端

### 如何安装 make-fetch-happen？

在项目目录运行 npm install make-fetch-happen，或使用 pnpm add / yarn add / bun add。

### make-fetch-happen 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/make-fetch-happen 是否存在。

### make-fetch-happen 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### make-fetch-happen 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.22\.2 \|\| ^24\.15\.0 \|\| \>=26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### make-fetch-happen 可以商用吗？

make-fetch-happen 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### make-fetch-happen 的下载量有多少？

根据 npm 官方下载统计，make-fetch-happen 在 2026/10/05 – 2026/11/03 这 30 天内被下载 122,004,087 次，日均约 4,066,803 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### make-fetch-happen 还在维护吗？

最新版本 16\.0\.1 发布于 2026/05/27（5 个月前）；至今共发布 119 个版本，其中过去 12 个月发布了 6 个；首次发布于 2017/03/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。