# content-disposition 中文文档

规范地址：https://npmcn.com/package/content-disposition/

版本：3\.0\.0
npm 元数据更新时间：2026-08-13T20:29:17.169Z
中文译文更新时间：2026-11-04T20:12:32.354Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：49.7 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2014-09-19T05:02:12.936Z
- 最新版本发布：2026-08-13T20:29:16.841Z
- 近 30 天下载量：641388857（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 5 个）

## 中文简介

创建并解析Content-Disposition报头

## 安装

```sh
npm install content-disposition
```

也可以使用：`pnpm add content-disposition`、`yarn add content-disposition`、`bun add content-disposition`

## README

# 附加项

[![NPM Version](https://img.shields.io/npm/v/content-disposition)](https://www.npmjs.com/package/content-disposition) [![NPM Downloads](https://img.shields.io/npm/dm/content-disposition)](https://www.npmjs.com/package/content-disposition) [![Node.js Version](https://img.shields.io/node/v/content-disposition)](https://nodejs.org/en/download) [![Build Status](https://img.shields.io/github/actions/workflow/status/jshttp/content-disposition/ci.yml)](https://github.com/jshttp/content-disposition/actions/workflows/ci.yml) [![Test Coverage](https://img.shields.io/coverallsCoverage/github/jshttp/content-disposition)](https://coveralls.io/github/jshttp/content-disposition?branch=master)

创建和解析HTTP `Content-Disposition` 头

## 安装

```sh
$ npm install content-disposition
```

## API

```js
import { create, parse, format } from 'content-disposition';
```

### 创建(文件名,选择)

创建附件 `Content-Disposition` 头值使用给定的文件名， 如果提供的。这个 `filename` 是可选的，如果不需要文件名，但是您 想要指定 `options`,设置 `filename` 来 `undefined`。

```js
res.setHeader('Content-Disposition', create('∫ maths.pdf'));
```

**请注意** HTTP报头是ISO-8859-1字符集。如果你在写这篇文章 头通过的方式不同于 `setHeader` 在Node.js中，您需要指定 这个 `'binary'` 在Node.js中编码。

#### 选项

`contentDisposition` 在options对象中接受这些属性。

##### 回退

如果 `filename` 选项在US-ASCII之外，则文件名实际上是 存储在一个补充字段中，用于支持Unicode文件名和 自动生成US-ASCII版本的文件名。

指定US-ASCII文件名以覆盖自动生成或 禁用全部生成，默认为 `true`。

-   字符串将指定要使用的US-ASCII文件名来代替automatic 的一代。
-   `false` 将禁用包括US-ASCII文件名，只包括 Unicode版本（除非文件名已经是US-ASCII）。
-   `true` 如果文件名在US-ASCII之外，将启用自动生成。

如果 `filename` 选项是US-ASCII，该选项被指定并具有 不同的值，则 `filename` 选项在扩展字段中编码 这一组作为后备字段，即使它们都是US-ASCII。

##### 类型

指定处置类型，默认为 `"attachment"`。这也可以是 `"inline"`，或任何其他值(除inline外的所有值都被视为 `attachment`，但如果双方同意，可以传达额外的信息 它)。

### parse (string,选项)

```js
const disposition = parse(
  'attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt',
);
```

解析 `Content-Disposition` 标题字符串。这将自动处理扩展 （"Unicode"）参数，通过解码并在标准下提供 参数名称。这将返回一个具有以下属性的对象：

-   `type`：处置类型（总是小写）。例子: `'attachment'`
    
-   `parameters`：参数配置（参数名）中的参数对象 总是用小写字母和扩展版本替换非扩展版本)。例子: `{filename: "€ rates.txt"}`
    

#### 选项

##### 多部分

使用浏览器解析参数 `multipart/form-data` 的行为。

```js
parse('form-data; name="file"; filename="the %22plans%22.pdf"', {
  multipart: true,
});
```

##### 扩展

解码时自动解析RFC 5987扩展报头参数 参数，默认为 `true`。

### 格式(obj选项)

```js
const disposition = format({
  type: 'attachment',
  parameters: {
    filename: '€ rates.txt',
  },
});
```

将对象格式化为a `Content-Disposition` 标题字符串。这个自动 处理扩展（"Unicode"）参数并返回一个字符串。例子: `'attachment; filename*=UTF-8''%E2%82%AC%20rates.txt'`

#### 选项

##### 多部分

使用浏览器格式化参数 `multipart/form-data` 的行为。这个报价 参数值，转义 `"` 作为 `%22`，并直接写入Unicode值 而不是使用扩展参数。

```js
format(
  {
    type: 'form-data',
    parameters: { name: 'file', filename: '€ rates.txt' },
  },
  { multipart: true },
);
```

##### 扩展

使用RFC 5987扩展头参数编码Unicode参数值 如。 `filename*=`，默认为 `true`。

## 例子

### 发送一个文件供下载

```js
import fs from 'node:fs';
import http from 'node:http';
import { create } from 'content-disposition';
import onFinished from 'on-finished';

const filePath = '/path/to/public/plans.pdf';

http.createServer(function onRequest(req, res) {
  // set headers
  res.setHeader('Content-Type', 'application/pdf');
  res.setHeader('Content-Disposition', create(filePath));

  // send file
  const stream = fs.createReadStream(filePath);
  stream.pipe(res);
  onFinished(res, function () {
    stream.destroy();
  });
});
```

## 当地的演示

在本地运行上传检查器：

```sh
npm run demo
```

然后打开 `http://127.0.0.1:3000` 在浏览器中。该演示允许您上传文件，检查浏览器发送的多部分上传部分头，并将它们与下载进行比较 `Content-Disposition` 这个包生成的头文件。

## 测试

```sh
$ npm test
```

## 参考文献

-   [超文本传输协议——HTTP/1.1](https://datatracker.ietf.org/doc/html/rfc2616)
-   [RFC 5987：超文本传输协议（HTTP）报头字段参数的字符集和语言编码](https://datatracker.ietf.org/doc/html/rfc5987)
-   [RFC 6266：超文本传输协议（HTTP）中内容处理头字段的使用](https://datatracker.ietf.org/doc/html/rfc6266)
-   [RFC 8187：指示HTTP报头字段参数的字符编码和语言](https://datatracker.ietf.org/doc/html/rfc8187)
-   [HTML生活标准：多部分表单数据](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#multipart-form-data)
-   [HTTP内容处理报头字段（RFC 6266）和RFC 2047、2231和5987中定义的编码的测试用例](http://greenbytes.de/tech/tc2231/)

## 许可证

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

## 常见问题

### content-disposition 是什么？

创建并解析Content-Disposition报头

### 如何安装 content-disposition？

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

### content-disposition 支持 TypeScript 吗？

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

### content-disposition 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### content-disposition 需要什么版本的 Node\.js？

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

### content-disposition 可以商用吗？

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

### content-disposition 的下载量有多少？

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

### content-disposition 还在维护吗？

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