# @fastify/etag 中文文档

规范地址：https://npmcn.com/package/%40fastify/etag/

版本：6\.2\.2
npm 元数据更新时间：2026-11-05T21:51:13.324Z
中文译文更新时间：2026-11-14T11:19:23.585Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：41.6 kB，20 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2022-04-27T13:51:02.812Z
- 最新版本发布：2026-11-05T21:51:12.962Z
- 近 30 天下载量：501422（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 3 个）

## 中文简介

为 HTTP 响应自动生成 etags, 为快取

## 安装

```sh
npm install @fastify/etag
```

也可以使用：`pnpm add @fastify/etag`、`yarn add @fastify/etag`、`bun add @fastify/etag`

## README

# @ fastify/ etag

[![CI](https://github.com/fastify/fastify-etag/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/fastify-etag/actions/workflows/ci.yml) [![NPM version](https://img.shields.io/npm/v/@fastify/etag.svg?style=flat)](https://www.npmjs.com/package/@fastify/etag) [![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard)

用于 [快捷化](https://fastify.dev/) 自动生成 HTTP ETags 的 [RFC2616-sec13 (英语)](https://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html)。 。 。 .

插件可以在ETag匹配如果-无匹配头时可选择发送304状态代码.

## 安装

```sh
npm i @fastify/etag
```

### 兼容性

| 插件版本 | 快速化版本 |
| --- | --- |
| `>=6.x` | `^5.x` |
| `>=4.x <6.x` | `^4.x` |
| `^3.x` | `^3.x` |
| `>=1.x <3.x` | `^2.x` |

请注意,如果一个快取版本没有支持,那么该插件的相应版本也一样 上表列出. 见 [快速化 LTS 政策](https://github.com/fastify/fastify/blob/main/docs/Reference/LTS.md) 更多细节.

## 示例

```js
'use strict'

const Fastify = require('fastify')
const Etag = require('@fastify/etag')

const app = Fastify()
app.register(Etag)

app.get('/', async (req, reply) => {
  return { hello: 'world' }
})

app.get('/manual-etag', async (req, reply) => {
  // This will disable automatic ETag generation
  // It will still return a 304 if the ETag matches
  reply.header('etag', '"foobar"')
  return 'world'
})

app.listen(3000)
```

## 插件选项

-   `algorithm`: 所有散列算法 : [`crypto`](https://nodejs.org/api/crypto.html) 模块支持。 默认 : `'sha1'`. (中文(简体) )`'fnv1a'` 已贬值; 使用 `hashFn: Etag.fnv1a` 改为. )
-   `hashFn`: 用于生成ETags的函数(称为 `string` 或者说 `Buffer` 有效载荷;返回未引用的散列。 提供时, `algorithm` 选项将被忽略。 默认 : `undefined`。 。 。 .
-   `weak`:默认生成弱ETags. 默认 : `false`。 。 。 .

### 使用自定义散列函数

```js
'use strict'

const Fastify = require('fastify')
const Etag = require('@fastify/etag')

const app = Fastify()
app.register(Etag, {
  hashFn: Etag.fnv1a // Use fnv1a provided by @fastify/etag
})

app.get('/', async (req, reply) => {
  return { hello: 'world' }
})

app.get('/manual-etag', async (req, reply) => {
  // This will disable automatic ETag generation
  // It will still return a 304 if the ETag matches
  reply.header('etag', '"foobar"')
  return 'world'
})

app.listen(3000)
```

### 自动 304 状态代码

默认情况下,插件会在ETag与如果-none-match请求头指定的Etag相等时发送304状态代码.

这常常是理想的行为,但可以通过设置被禁用 `replyWith304: false`。 。 。 .

## 承认

Fnv1a逻辑来自Travis Webb([翻译:](https://github.com/tjwebb)) 的,为: [https://github.com/tjwebb/fnv-plus (中文(简体) )](https://github.com/tjwebb/fnv-plus),实际执行有助于 `fnv-plus` 以 [@ 德苏塔克](https://github.com/desudesutalk) 内 [https://github.com/tjwebb/fnv-plus/pull/9 (中文(简体) )](https://github.com/tjwebb/fnv-plus/pull/9),并改编自 [@ SukkaW (英语)](https://github.com/SukkaW) 用于支持缓冲.

## 基准

生成一个母鹿总是比生成一个母鹿慢。 生成速度也取决于有效载荷大小和类型(缓冲或弦):

-   对于很小的有效载荷( < 2克b),使用 `'fnv1a'`
-   2 mb 以上的缓冲器,使用 `'md5'`
-   在所有其他情况下,使用 `'sha1'` (默认)
-   YMMV,见 [这个问题](https://github.com/fastify/fastify-etag/issues/91) 其他算法,如小有效载荷的crc32和大缓冲器的murhash3-wasm,其性能优于上述建议
-   任何电阻生成都会导致至少10%的操作量减少(对于巨大的有效载荷,操作量减少50%)

## 许可证

许可证根据 [麻省理工学院](https://npmcn.com/package/%40fastify/etag/LICENSE)。 。 。 .

## 常见问题

### @fastify/etag 是什么？

为 HTTP 响应自动生成 etags, 为快取

### 如何安装 @fastify/etag？

在项目目录运行 npm install @fastify/etag，或使用 pnpm add / yarn add / bun add。

### @fastify/etag 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fastify/etag 支持 ESM 还是 CommonJS？

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

### @fastify/etag 可以商用吗？

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

### @fastify/etag 的下载量有多少？

根据 npm 官方下载统计，@fastify/etag 在 2026/10/15 – 2026/11/13 这 30 天内被下载 501,422 次，日均约 16,714 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fastify/etag 还在维护吗？

最新版本 6\.2\.2 发布于 2026/11/06（8 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 3 个；首次发布于 2022/04/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。