# send 中文文档

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

版本：1\.2\.1
npm 元数据更新时间：2025-12-15T19:36:12.171Z
中文译文更新时间：2026-11-04T22:20:54.276Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：32.2 kB，4 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>= 18
- 运行依赖：11 个
- 首次发布：2012-07-04T02:26:08.255Z
- 最新版本发布：2025-12-15T19:36:11.862Z
- 近 30 天下载量：704476817（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：69（近 12 个月 2 个）

## 中文简介

更好的流静态文件服务器，支持Range和条件get

## 安装

```sh
npm install send
```

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

## README

# 发送

[![NPM Version](https://badgen.net/npm/v/send)](https://npmjs.org/package/send) [![NPM Downloads](https://badgen.net/npm/dm/send)](https://npmjs.org/package/send) [![CI](https://badgen.net/github/checks/pillarjs/send/master?label=linux)](https://github.com/pillarjs/send/actions/workflows/ci.yml) [![Test Coverage](https://badgen.net/coveralls/c/github/pillarjs/send/master)](https://coveralls.io/r/pillarjs/send?branch=master)

Send是一个库，用于将文件系统中的文件作为http响应流式传输 支持部分响应（Ranges）、条件get协商（If-Match）、 If-Unmodified-Since, if - nonmatch, If-Modified-Since)，测试覆盖率高， 以及可用于采取适当行动的粒度事件 应用程序或框架。

希望提供映射到url的整个文件夹？试一试 [为静态](https://www.npmjs.org/package/serve-static)。

## 安装

这是一个 [node . js](https://nodejs.org/en/) 模块可通过 [npm注册表](https://www.npmjs.com/)． 安装是使用 [`npm install` 命令](https://docs.npmjs.com/getting-started/installing-npm-packages-locally)：

```bash
$ npm install send
```

## API

```js
var send = require('send')
```

### 发送（请求，路径，\[选项\]）

新建一个 `SendStream` 对于要发送到的给定路径 `res`。这个 `req` 是 Node.js的HTTP请求和 `path` 是要发送的urlencoded路径(urlencoded， 不是实际的文件系统路径)。

#### 选项

##### acceptRanges

启用或禁用接受远程请求，默认为true。 禁用此功能将无法发送 `Accept-Ranges` 忽略内容 的 `Range` 请求头。

##### cacheControl

启用或禁用设置 `Cache-Control` 响应头，默认为 真实的。禁用此功能将忽略 `immutable` 和 `maxAge` 选项。

##### .

设置遇到“dotfiles”时如何处理。dotfile是一个文件 或以点（"."）开头的目录。注意这个检查是在 路径本身，而不检查该路径是否在 磁盘。如果 `root` ，则只有根目录上面的dotfiles是 检查(即根本身可以在dotfile设置时 “否认”)。

-   `'allow'` 对dotfiles没有特殊处理。
-   `'deny'` 对dotfile的任何请求发送一个403。
-   `'ignore'` 假装dotfile不存在，然后返回404。

默认值为 _类似的_ 来 `'ignore'`，除了 这个默认值不会忽略目录中的文件 带圆点，用于向后兼容。

##### 结束

流结束时的字节偏移量，默认为文件长度 - 1。结束是包含在流中的意思 `end: 3` 将包括 流中的第四个字节。

##### etag

启用或禁用etag生成，默认为true。

##### 扩展

如果给定的文件不存在，尝试添加给定的扩展名之一， 按照给定的顺序。默认情况下，这是禁用的(设置为 `false`）. 一个 示例值，将提供无扩展的HTML文件： `['html', 'htm']`。 如果请求的文件已经有扩展名，则跳过此操作。

##### 不可变的

启用或禁用 `immutable` 的指令 `Cache-Control` 响应 头，默认为 `false`． 如果设置为 `true`, `maxAge` 选择应 还指定启用缓存。这个 `immutable` 指令将阻止 的生命周期内支持客户端发出有条件请求 `maxAge` 选项以检查文件是否已更改。

##### 指数

默认情况下，send支持“index.html”文件，禁用此功能 集 `false` 或者提供一个新的索引，传递一个字符串或数组 按优先顺序。

##### lastModified

启用或禁用 `Last-Modified` 头，默认为true。使用文件 系统上次修改的值。

##### maxAge

为http缓存提供以毫秒为单位的最大年龄，默认为0。 对象接受的字符串 [女士](https://www.npmjs.org/package/ms#readme) 模块。

##### 根

提供相对于 `path`。

##### 开始

流开始时的字节偏移量，默认为0。开始是包容的， 意义 `start: 2` 将包括流中的第三个字节。

#### 事件

这个 `SendStream` 是事件发射器，并将发出以下事件：

-   `error` 发生错误 `(err)`
-   `directory` 请求一个目录 `(res, path)`
-   `file` 请求文件 `(path, stat)`
-   `headers` 即将在文件上设置头文件 `(res, path, stat)`
-   `stream` 文件流已开始 `(stream)`
-   `end` 流媒体已经完成

#### .pipe

这个 `pipe` 方法用于将响应管道传输到Node.js的HTTP响应中 对象,通常 `send(req, path, options).pipe(res)`。

## 错误处理

默认为no `error` 侦听器存在时，将自动响应 否则你可以完全控制响应，也就是说你可能会显示一个5xx 页面等。

## 缓存

它 _不_ 执行内部缓存时，应该使用反向代理缓存 比如清漆，或者那些叫做cdn的东西。如果你的 应用程序足够小，可以从单节点内存中获益 缓存，它足够小，根本不需要缓存；)。

## 调试

启用 `debug()` 仪表输出输出 **调试**：

```
$ DEBUG=send node app
```

## 运行测试

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

## 例子

### 提供一个特定的文件

这个简单的示例将向所有请求发送一个特定的文件。

```js
var http = require('http')
var send = require('send')

var server = http.createServer(function onRequest (req, res) {
  send(req, '/path/to/index.html')
    .pipe(res)
})

server.listen(3000)
```

### 从一个目录提供所有文件

这个简单的示例将提供所有文件 指定目录作为顶级目录。例如，请求 `GET /foo.txt` 将寄回 `/www/public/foo.txt`。

```js
var http = require('http')
var parseUrl = require('parseurl')
var send = require('send')

var server = http.createServer(function onRequest (req, res) {
  send(req, parseUrl(req).pathname, { root: '/www/public' })
    .pipe(res)
})

server.listen(3000)
```

### 自定义文件类型

```js
var extname = require('path').extname
var http = require('http')
var parseUrl = require('parseurl')
var send = require('send')

var server = http.createServer(function onRequest (req, res) {
  send(req, parseUrl(req).pathname, { root: '/www/public' })
    .on('headers', function (res, path) {
      switch (extname(path)) {
        case '.x-mt':
        case '.x-mtt':
          // custom type for these extensions
          res.setHeader('Content-Type', 'application/x-my-type')
          break
      }
    })
    .pipe(res)
})

server.listen(3000)
```

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

这是提供目录结构的一个示例 显示目录列表的自定义函数。

```js
var http = require('http')
var fs = require('fs')
var parseUrl = require('parseurl')
var send = require('send')

// Transfer arbitrary files from within /www/example.com/public/*
// with a custom handler for directory listing
var server = http.createServer(function onRequest (req, res) {
  send(req, parseUrl(req).pathname, { index: false, root: '/www/public' })
    .once('directory', directory)
    .pipe(res)
})

server.listen(3000)

// Custom directory handler
function directory (res, path) {
  var stream = this

  // redirect to trailing slash for consistent url
  if (!stream.hasTrailingSlash()) {
    return stream.redirect(path)
  }

  // get directory list
  fs.readdir(path, function onReaddir (err, list) {
    if (err) return stream.error(err)

    // render an index for the directory
    res.setHeader('Content-Type', 'text/plain; charset=UTF-8')
    res.end(list.join('\n') + '\n')
  })
}
```

### 从根目录提供自定义错误处理

```js
var http = require('http')
var parseUrl = require('parseurl')
var send = require('send')

var server = http.createServer(function onRequest (req, res) {
  // your custom error-handling logic:
  function error (err) {
    res.statusCode = err.status || 500
    res.end(err.message)
  }

  // your custom headers
  function headers (res, path, stat) {
    // serve all files for download
    res.setHeader('Content-Disposition', 'attachment')
  }

  // your custom directory handling logic:
  function redirect () {
    res.statusCode = 301
    res.setHeader('Location', req.url + '/')
    res.end('Redirecting to ' + req.url + '/')
  }

  // transfer arbitrary files from within
  // /www/example.com/public/*
  send(req, parseUrl(req).pathname, { root: '/www/public' })
    .on('error', error)
    .on('directory', redirect)
    .on('headers', headers)
    .pipe(res)
})

server.listen(3000)
```

## 许可证

[麻省理工学院](https://npmcn.com/package/send/LICENSE)

## 常见问题

### send 是什么？

更好的流静态文件服务器，支持Range和条件get

### 如何安装 send？

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

### send 支持 TypeScript 吗？

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

### send 需要什么版本的 Node\.js？

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

### send 可以商用吗？

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

### send 的下载量有多少？

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

### send 还在维护吗？

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