# @fastify/send 中文文档

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

版本：4\.2\.1
npm 元数据更新时间：2026-11-02T22:38:42.858Z
中文译文更新时间：2026-11-14T11:07:15.088Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：146 kB，59 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2023-01-11T10:39:05.796Z
- 最新版本发布：2026-11-02T22:38:42.521Z
- 近 30 天下载量：30401022（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 4 个）

## 中文简介

在 Range 和有条件的 GET 支持下更好地流出静态文件服务器

## 安装

```sh
npm install @fastify/send
```

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

## README

# @ fastify/ 发送

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

发送是一个用于从文件系统流出文件作为 HTTP 响应的库 支持部分响应(范围),有条件的GET谈判(如果-Match, 若-未修改-辛,若-无-Match,若-已修改-辛,高测试覆盖率, 和颗粒性事件,可借以在 应用或框架.

## 安装

这是一个 [节点.js](https://nodejs.org/en/) 模块 [npm 登记](https://www.npmjs.com/)。安装使用 [`npm install` 命令](https://docs.npmjs.com/downloading-and-installing-packages-locally)数字 :

```bash
$ npm install @fastify/send
```

### 类型脚本

`@types/mime@3` 如果想要使用类型脚本,必须使用; `@types/mime@4` 删除了 `mime` 类型.

```bash
$ npm install -D @types/mime@3
```

## API 密码

```js
const send = require('@fastify/send')
```

### 发送( req, 路径, \[选项\])

提供 `statusCode`, (中文(简体) ), `headers`,以及 `stream` 给定路径发送到 `res`编辑 `req` 是节点.js HTTP 请求和 `path` 是一个 urlencoded 路径 以发送(urlencoded,而非实际文件系统路径).

#### 选项

##### 接受区域

启用或禁用接受范围请求, 默认为真实 . 禁用此选项不会发送 `Accept-Ranges` 忽略内容 会 议 日 程 和 议 程 `Range` 请求头.

##### 缓存控制

启用或禁用设置 `Cache-Control` 响应头,默认为 没错 禁用会忽略 `immutable` 财务报告和审定财务报表 `maxAge` 选项.

##### 内容类型

默认情况下,此库使用 `mime` 模块设置 `Content-Type` 以请求的文件扩展名为基础的响应.

要禁用此功能, 设置 `contentType` 改为 `false`。 。 。 . 这个 `Content-Type` 如果已禁用, 需要手动设置页眉 .

##### 点文件

设定“ 点文件” 遇到时如何处理 。 点文件是一个文件 或者以点("")开头的目录. 注意此检查是在 路径本身而不检查路径是否存在于 磁盘。 若为 `root` 指定,只有根上方的点文件是 选中( 即当设置时, 根本身可以在点文件中) 以"dey"来表示.

-   `'allow'` 对点文件没有特殊待遇.
-   `'deny'` 发送一个403 对于任何一个点文件的请求.
-   `'ignore'` 假装点文件不存在 404.

默认值为 _类似_ 改为 `'ignore'`,但 此默认不会忽略目录中开始的文件 带有点,用于后相相.

##### 结束

流结束的字节相抵,默认为文件长度 减一. 结束在溪流中是包容性的,意思是 `end: 3` 将包括 溪中第四字节.

##### 爱塔格

启用或禁用 etag 生成, 默认为真实 .

##### 扩展

如果给定文件不存在,请尝试附加给定的扩展名之一, 以给定顺序。 默认情况下,此选项已禁用( 设置为 `false`) (中文(简体) ). 一个 为无扩展名的 HTML 文件服务的示例值 : `['html', 'htm']`。 。 。 . 如果请求的文件已有扩展名, 则跳过 .

##### 不可改变

启用或禁用 `immutable` 指令中 `Cache-Control` 回应 页眉,默认为 `false`如果设置为 `true`,则 `maxAge` 选项应当 也指定可以缓存。 这个 `immutable` 指令将防止 支持客户在其存在期间提出有条件请求 `maxAge` 选项以检查文件是否更改.

##### 指数

默认发送支持“ index.html” 文件以禁用此功能 设定 `false` 或提供新索引通过字符串或数组 以优先顺序排列.

##### 最后修改

启用或禁用 `Last-Modified` 标题,默认为真. 使用文件 系统的最后修改值.

##### 最大年龄

为 HTTP 缓存提供以毫秒为单位的最大年龄, 默认为 0 . 也可以是被 [分钟](https://www.npmjs.com/package/ms) 模块.

##### 最大线程切变大小

指定最大响应内容大小,默认为整个文件大小. 当 `acceptRanges` 这是真的.

##### 文件夹

以最终选中的文件的绝对路径和文件系统统计调用 在文件解析后,但在回复处理和文件流创建之前. 召回可能是同步的,也可能是还原承诺. 如果它还回来, `send` 等待它解决。 如果召回 放弃或返回的承诺 拒绝,操作中止 `send()` 拒绝.

##### 根号

服务文件相对于 `path`。 。 。 .

##### 开始

启动流的字节相抵,默认为 0。 开始是包容性的, 含义 `start: 2` 将包含在溪流中的第3字节.

##### 高水压

提供时, 此选项将设定内部的字节数最大值 缓冲器在从原始资源中读取之前会保持. 如果您省略了此选项( 或通过未定义的) , 节点会回到 其可读二进制流的内置默认值.

### .mime (英语)

这个 `mime` 导出是全球实例 [`mime` npm 模块](https://www.npmjs.com/package/mime)。 。 。 .

用于配置与文件扩展名相关的 MIME 类型 以及关于如何解决文件的 MIME 类型的其他选项(如 用于未知文件扩展名的默认类型).

## 缓存

没错 _没有_ 执行内部缓存, 您应该使用反向代理缓存 比如这个的Varnish 或者那些叫CDN的花花公子 狦 应用程序小到能够从单节点内存中受益 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}它已经足够小了 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}它完全不需要被挖出 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}.

## 调试

启用 `debug()` 仪器输出导出 **诺德-DEBUG**数字 :

```
$ NODE_DEBUG=send node app
```

## 正在测试

```
$ npm install
$ npm test
```

## 实例

### 提供特定文件

这个简单的例子会向所有请求发送一个特定文件.

```js
const http = require('node:http')
const send = require('send')

const server = http.createServer(async function onRequest (req, res) {
  const { statusCode, headers, stream } = await send(req, '/path/to/index.html')
  res.writeHead(statusCode, headers)
  stream.pipe(res)
})

server.listen(3000)
```

### 服务目录中的所有文件

这个简单的例子将只服务于一个 指定目录为顶级。 例如,请求 `GET /foo.txt` 将返回 `/www/public/foo.txt`。 。 。 .

```js
const http = require('node:http')
const parseUrl = require('parseurl')
const send = require('@fastify/send')

const server = http.createServer(async function onRequest (req, res) {
  const { statusCode, headers, stream } = await send(req, parseUrl(req).pathname, { root: '/www/public' })
  res.writeHead(statusCode, headers)
  stream.pipe(res)
})

server.listen(3000)
```

### 自定义文件类型

```js
const http = require('node:http')
const parseUrl = require('parseurl')
const send = require('@fastify/send')

// Default unknown types to text/plain
send.mime.default_type = 'text/plain'

// Add a custom type
send.mime.define({
  'application/x-my-type': ['x-mt', 'x-mtt']
})

const server = http.createServer(function onRequest (req, res) {
  const { statusCode, headers, stream } = await send(req, parseUrl(req).pathname, { root: '/www/public' })
  res.writeHead(statusCode, headers)
  stream.pipe(res)
})

server.listen(3000)
```

### 自定义目录索引视图

这是为目录结构服务的一个例子,其中包含: 自定义功能,用于提供目录的列表.

```js
const http = require('node:http')
const fs = require('node:fs')
const parseUrl = require('parseurl')
const send = require('@fastify/send')

// Transfer arbitrary files from within /www/example.com/public/*
// with a custom handler for directory listing
const server = http.createServer(async function onRequest (req, res) {
  const { statusCode, headers, stream, type, metadata } = await send(req, parseUrl(req).pathname, { index: false, root: '/www/public' })
  if(type === 'directory') {
    // get directory list
    const list = await readdir(metadata.path)
    // render an index for the directory
    res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
    res.end(list.join('\n') + '\n')
  } else {
    res.writeHead(statusCode, headers)
    stream.pipe(res)
  }
})

server.listen(3000)
```

### 从自定义错误处理的根目录服务

```js
const http = require('node:http')
const parseUrl = require('parseurl')
const send = require('@fastify/send')

const server = http.createServer(async function onRequest (req, res) {
  // transfer arbitrary files from within
  // /www/example.com/public/*
  const { statusCode, headers, stream, type, metadata } = await send(req, parseUrl(req).pathname, { root: '/www/public' })
  switch (type) {
    case 'directory': {
      // your custom directory handling logic:
      res.writeHead(301, {
        'Location': metadata.requestPath + '/'
      })
      res.end('Redirecting to ' + metadata.requestPath + '/')
      break
    }
    case 'error': {
      // your custom error-handling logic:
      res.writeHead(metadata.error.status ?? 500, {})
      res.end(metadata.error.message)
      break
    }
    default: {
      // your custom headers
      // serve all files for download
      res.setHeader('Content-Disposition', 'attachment')
      res.writeHead(statusCode, headers)
      stream.pipe(res)
    }
  }
})

server.listen(3000)
```

## 许可证

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

## 常见问题

### @fastify/send 是什么？

在 Range 和有条件的 GET 支持下更好地流出静态文件服务器

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

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

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

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

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

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

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

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

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

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

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

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