# @discordjs/form-data 中文文档

规范地址：https://npmcn.com/package/%40discordjs/form-data/

版本：3\.0\.1
npm 元数据更新时间：2022-07-17T22:08:39.852Z
中文译文更新时间：2026-11-12T11:11:14.008Z
软件包许可：MIT

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

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

弃用说明：Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

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

- 包体积（解压后）：30.7 kB，7 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 6
- 运行依赖：3 个
- 首次发布：2020-04-16T11:07:23.376Z
- 最新版本发布：2020-04-16T11:07:23.698Z
- 近 30 天下载量：177902（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

一个创建可读"多部分/形式-数据"流的库. 可用于提交表格和文件上传到其他网络应用程序.

## 安装

```sh
npm install @discordjs/form-data
```

也可以使用：`pnpm add @discordjs/form-data`、`yarn add @discordjs/form-data`、`bun add @discordjs/form-data`

## README

# 窗体数据 [![NPM Module](https://img.shields.io/npm/v/form-data.svg)](https://www.npmjs.com/package/form-data) [![Join the chat at https://gitter.im/form-data/form-data](http://form-data.github.io/images/gitterbadge.svg)](https://gitter.im/form-data/form-data)

创建可读图书馆 `"multipart/form-data"` 流经. 可用于提交表格和文件上传到其他网络应用程序.

此库的API 灵感来自 [XMLHttp 请求-2 FormData 接口](http://dev.w3.org/2006/webapi/XMLHttpRequest-2/Overview.html#the-formdata-interface)。 。 。 .

[![Linux Build](https://img.shields.io/travis/form-data/form-data/master.svg?label=linux:6.x-12.x)](https://travis-ci.org/form-data/form-data) [![MacOS Build](https://img.shields.io/travis/form-data/form-data/master.svg?label=macos:6.x-12.x)](https://travis-ci.org/form-data/form-data) [![Windows Build](https://img.shields.io/travis/form-data/form-data/master.svg?label=windows:6.x-12.x)](https://travis-ci.org/form-data/form-data)

[![Coverage Status](https://img.shields.io/coveralls/form-data/form-data/master.svg?label=code+coverage)](https://coveralls.io/github/form-data/form-data?branch=master) [![Dependency Status](https://img.shields.io/david/form-data/form-data.svg)](https://david-dm.org/form-data/form-data)

## 安装

```
npm install --save form-data
```

## 使用量

在这个例子中,我们正在构建一个包含有字符串的三个字段的表格, 缓冲器和文件流.

```javascript
var FormData = require('form-data');
var fs = require('fs');

var form = new FormData();
form.append('my_field', 'my value');
form.append('my_buffer', new Buffer(10));
form.append('my_file', fs.createReadStream('/foo/bar.jpg'));
```

您也可以使用 http- response 流 :

```javascript
var FormData = require('form-data');
var http = require('http');

var form = new FormData();

http.request('http://nodejs.org/images/logo.png', function(response) {
  form.append('my_field', 'my value');
  form.append('my_buffer', new Buffer(10));
  form.append('my_logo', response);
});
```

或说@mikeal's [请求](https://github.com/request/request) 流线 :

```javascript
var FormData = require('form-data');
var request = require('request');

var form = new FormData();

form.append('my_field', 'my value');
form.append('my_buffer', new Buffer(10));
form.append('my_logo', request('http://nodejs.org/images/logo.png'));
```

为了向网络应用程序提交此表, 请调用 `submit(url, [callback])` 方法 :

```javascript
form.submit('http://example.org/', function(err, res) {
  // res – response object (http.IncomingMessage)  //
  res.resume();
});

```

对于更先进的请求操纵 `submit()` 方法返回 `http.ClientRequest` 对象,或者可以从备选提交方法中选择.

### 自定义选项

您可以提供自定义选项, 例如 `maxDataSize`数字 :

```javascript
var FormData = require('form-data');

var form = new FormData({ maxDataSize: 20971520 });
form.append('my_field', 'my value');
form.append('my_buffer', /* something big */);
```

现有备选方案清单可见于 [组合-流](https://github.com/felixge/node-combined-stream/blob/master/lib/combined_stream.js#L7-L15)

### 备选提交方法

您可以使用节点的 http 客户端接口 :

```javascript
var http = require('http');

var request = http.request({
  method: 'post',
  host: 'example.org',
  path: '/upload',
  headers: form.getHeaders()
});

form.pipe(request);

request.on('response', function(res) {
  console.log(res.statusCode);
});
```

或者如果你更喜欢 `'Content-Length'` 要为您设定的标题 :

```javascript
form.submit('example.org/upload', function(err, res) {
  console.log(res.statusCode);
});
```

要使用自定义标题和预知长度的部件 :

```javascript
var CRLF = '\r\n';
var form = new FormData();

var options = {
  header: CRLF + '--' + form.getBoundary() + CRLF + 'X-Custom-Header: 123' + CRLF + CRLF,
  knownLength: 1
};

form.append('my_buffer', buffer, options);

form.submit('http://example.com/', function(err, res) {
  if (err) throw err;
  console.log('Done');
});
```

表格数据可以识别并从常见类型的流中获取所有所需信息(`fs.readStream`, (中文(简体) ), `http.response` 财务报告和审定财务报表 `mikeal's request`),对于其他一些类型的流,您需要手动提供"文件"相关信息:

```javascript
someModule.stream(function(err, stdout, stderr) {
  if (err) throw err;

  var form = new FormData();

  form.append('file', stdout, {
    filename: 'unicycle.jpg', // ... or:
    filepath: 'photos/toys/unicycle.jpg',
    contentType: 'image/jpeg',
    knownLength: 19806
  });

  form.submit('http://example.com/', function(err, res) {
    if (err) throw err;
    console.log('Done');
  });
});
```

这个 `filepath` 属性覆盖 `filename` 并可能包含一个相对路径。 这通常用于上传 [目录中的多个文件](https://wicg.github.io/entries-api/#dom-htmlinputelement-webkitdirectory)。 。 。 .

对于边缘大小写,如 POST 请求使用查询字符串的 URL 或者通过 HTTP 认证证书, 对象可以传递到 `form.submit()` 作为第一个参数 :

```javascript
form.submit({
  host: 'example.com',
  path: '/probably.php?extra=params',
  auth: 'username:password'
}, function(err, res) {
  console.log(res.statusCode);
});
```

如果您还需要发送带有 POST 请求的自定义 HTTP 信头, 您可以使用 `headers` 第一个参数中的密钥 `form.submit()`数字 :

```javascript
form.submit({
  host: 'example.com',
  path: '/surelynot.php',
  headers: {'x-test-header': 'test-header-value'}
}, function(err, res) {
  console.log(res.statusCode);
});
```

### 方法

-   [_虚拟_ 附录( e) **字符串** _字段_, (中文(简体) ), **混合** _价值_ \[, **混合** _选项_\[ \]](https://github.com/form-data/form-data#void-append-string-field-mixed-value--mixed-options-)。 。 。 .
-   [_页眉_ 获取标题( E)**页眉** _用户页眉_\[ \]](https://github.com/form-data/form-data#array-getheaders-array-userheaders-)
-   [_字符串_ 获取边界( B)](https://github.com/form-data/form-data#string-getboundary)
-   [_缓冲_ 获取缓冲 ()](https://github.com/form-data/form-data#buffer-getbuffer)
-   [_整数_ 获取 LengthSync ()](https://github.com/form-data/form-data#integer-getlengthsync)
-   [_整数_ 获取 Length () **函数** _回调_ (中文(简体) )](https://github.com/form-data/form-data#integer-getlength-function-callback-)
-   [_布尔_ 已经知道Length( )](https://github.com/form-data/form-data#boolean-hasknownlength)
-   [_请求_ 提交( e) _段落_, (中文(简体) ), **函数** _回调_ (中文(简体) )](https://github.com/form-data/form-data#request-submit-params-function-callback-)
-   [_字符串_ 转到 String ()](https://github.com/form-data/form-data#string-tostring)

#### _虚拟_ 附录( e) **字符串** _字段_, (中文(简体) ), **混合** _价值_ \[, **混合** _选项_\[ \]

在表单中附加数据。 您可以提交任何格式(字符串、整数、布尔、缓冲等)。 然而,阵列不支持,需要被用户变成字符串.

```javascript
var form = new FormData();
form.append( 'my_string', 'my value' );
form.append( 'my_integer', 1 );
form.append( 'my_boolean', true );
form.append( 'my_buffer', new Buffer(10) );
form.append( 'my_array_as_json', JSON.stringify( ['bird','cute'] ) )
```

您可以为选项或对象提供字符串 .

```javascript
// Set filename by providing a string for options
form.append( 'my_file', fs.createReadStream('/foo/bar.jpg'), 'bar.jpg' );

// provide an object.
form.append( 'my_file', fs.createReadStream('/foo/bar.jpg'), {filename: 'bar.jpg', contentType: 'image/jpeg', knownLength: 19806} );
```

#### _页眉_ 获取标题( E)**页眉** _用户页眉_\[ \]

这种方法添加了正确的 `content-type` 给定数组的页眉 `userHeaders`。 。 。 .

#### _字符串_ 获取边界( B)

返回窗体Data的边界。 边界由26个组成 `-` 随后是24个数字 例如:

```javascript
--------------------------515890814546601021194782
```

_注:边界必须是独特的,可能不出现在数据中._

#### _缓冲_ 获取缓冲 ()

返回完整的窗体数据请求包, 作为缓冲器 。 您可以在 Axios 中插入此缓冲以发送多段数据 .

```javascript
var form = new FormData();
form.append( 'my_buffer', Buffer.from([0x4a,0x42,0x20,0x52,0x6f,0x63,0x6b,0x73]) );
form.append( 'my_file', fs.readFileSync('/foo/bar.jpg') );

axios.post( 'https://example.com/path/to/api',
            form.getBuffer(),
            form.getHeaders()
          )
```

**说明:** 由于输出为缓冲类型,只能附加被缓冲接受的类型: _字符串、 缓冲、 线程、 线程或类似线程的对象_。例如,ReadStream将会导致错误.

#### _整数_ 获取 LengthSync ()

与 `getLength` 但是同步的.

_注:获取 Length 同步 **没有** 计算流长._

#### _整数_ 获取 Length () **函数** _回调_ (中文(简体) )

返回 `Content-Length` 亚眠。 回调用于处理错误, 一旦长度被计算出来继续

```javascript
this.getLength(function(err, length) {
  if (err) {
    this._error(err);
    return;
  }

  // add content length
  request.setHeader('Content-Length', length);

  ...
}.bind(this));
```

#### _布尔_ 已经知道Length( )

检查添加值的长度是否为已知 .

#### _请求_ 提交( e) _段落_, (中文(简体) ), **函数** _回调_ (中文(简体) )

将表格提交网络应用程序.

```javascript
var form = new FormData();
form.append( 'my_string', 'Hello World' );

form.submit( 'http://example.com/', function(err, res) {
  // res – response object (http.IncomingMessage)  //
  res.resume();
} );
```

#### _字符串_ 转到 String ()

返回窗体数据为字符串。 如果您正在发送文件或缓冲器, 请不要使用此项 `getBuffer()` 换句话说.

### 与其他图书馆合并

#### 请求

使用表格提交 [请求](https://github.com/request/request)数字 :

```javascript
var formData = {
  my_field: 'my_value',
  my_file: fs.createReadStream(__dirname + '/unicycle.jpg'),
};

request.post({url:'http://service.com/upload', formData: formData}, function(err, httpResponse, body) {
  if (err) {
    return console.error('upload failed:', err);
  }
  console.log('Upload successful!  Server responded with:', body);
});
```

详情见 [请求读取](https://github.com/request/request#multipartform-data-multipart-form-uploads)。 。 。 .

#### 节点比对

您也可以使用 [节点比对](https://github.com/bitinn/node-fetch)数字 :

```javascript
var form = new FormData();

form.append('a', 1);

fetch('http://example.com', { method: 'POST', body: form })
    .then(function(res) {
        return res.json();
    }).then(function(json) {
        console.log(json);
    });
```

#### 轴

在节点中,您可以使用 [轴](https://github.com/axios/axios)数字 :

```javascript
const form = new FormData();
const stream = fs.createReadStream(PATH_TO_FILE);

form.append('image', stream);

// In Node.js environment you need to set boundary in the header field 'Content-Type' by calling method `getHeaders`
const formHeaders = form.getHeaders();

axios.post('http://example.com', form, {
  headers: {
    ...formHeaders,
  },
})
.then(response => response)
.catch(error => error)
```

## 页:1

-   `getLengthSync()` 方法 DNSN 不计算流长, 使用 `knownLength` 选项作为工作.
-   `getLength(cb)` 如果无法计算流长, 将会将错误作为调回的第一个参数( 例如, 使用自定义流 w/ o 发送) `knownLength`) (中文(简体) ).
-   `sbumit` 将不添加 `content-length` 如果形式长度未知或无法计算.
-   开始版本 `2.x` FormData 已放弃对 `node@0.10.x`。 。 。 .
-   开始版本 `3.x` FormData 已放弃对 `node@4.x`。 。 。 .

## 许可证

表格数据在 [麻省理工学院](https://npmcn.com/package/%40discordjs/form-data/License) 执照.

## 常见问题

### @discordjs/form-data 是什么？

一个创建可读"多部分/形式-数据"流的库\. 可用于提交表格和文件上传到其他网络应用程序\.注意：该包已被作者标记为弃用——Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

### 如何安装 @discordjs/form-data？

在项目目录运行 npm install @discordjs/form-data，或使用 pnpm add / yarn add / bun add。

### @discordjs/form-data 支持 TypeScript 吗？

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

### @discordjs/form-data 支持 ESM 还是 CommonJS？

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

### @discordjs/form-data 需要什么版本的 Node\.js？

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

### @discordjs/form-data 可以商用吗？

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

### @discordjs/form-data 的下载量有多少？

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

### @discordjs/form-data 还在维护吗？

最新版本 3\.0\.1 发布于 2020/04/16（6 年前）；至今共发布 1 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/04/16。作者已将其标记为弃用，新项目建议寻找替代方案。