告别小程序上传痛点：利用wx-formdata优雅实现FormData多文件上传
在微信小程序原生开发中，处理文件上传时常常会遇到一个棘手的问题：后端接口要求遵循标准的 multipart/form-data 协议，但小程序的运行环境并不支持浏览器的 FormData 对象。开发者往往被迫与原生 API 复杂的参数结构周旋，这不仅降低了开发效率，在处理多文件上传或文件与普通字段混传时，代码更是容易变得臃肿难读。
为了解决这一痛点，开源社区贡献了 wx-formdata 这一轻量级工具。它在小程序环境中通过纯 JavaScript 模拟实现了浏览器 FormData 对象的核心功能。
github项目地址：https://github.com/zlyboy/wx-formdata
用法
跟浏览器中的FormData对象类似 引入js文件
const FormData = require('./formData.js')new一个FormData对象
let formData = new FormData();调用它的append()方法来添加字段或者调用appendFile()方法添加文件
formData.append("name", "value");
formData.appendFile("file", filepath, "文件名");添加完成后调用它的getData()生成上传数据，之后调用小程序的wx.request提交请求
let data = formData.getData();
wx.request({
url: 'https://接口地址',
header: {
'content-type': data.contentType
},
data: data.buffer,
});成员函数
FormData.append()
语法
formData.append(name, value);参数
| 参数名 | 描述 |
|---|---|
| name | value中包含的数据对应的表单名称 |
| value | 表单的值 |
FormData.appendFile()
语法
formData.appendFile(name, filepath, fileName);参数
| 参数名 | 描述 |
|---|---|
| name | value中包含的数据对应的表单名称 |
| filepath | 文件路径 |
| fileName | 文件名【可选】 |
FormData.getData()
语法
let data = formData.getData();返回值对象属性
| 属性名 | 描述 |
|---|---|
| buffer | 表单数据的ArrayBuffer对象 |
| contentType | http请求Content-Type头部内容 |
核心特性与实现原理
该工具的核心在于手动构建符合 multipart/form-data 规范的二进制数据流。根据其文档，它的 API 设计非常直观：
1. 模拟标准接口：通过 new FormData() 创建实例，使用 append(name, value) 添加普通文本字段，使用 appendFile(name, filePath, fileName) 添加文件路径。
2. 二进制数据生成：调用 getData() 方法后，它会自动将所有字段和文件拼接成符合规范的 ArrayBuffer 对象，并返回对应的 content-type 请求头。
3. 无缝集成：生成的 ArrayBuffer 可直接作为 wx.request 的 data 参数传入，完美打通了从表单构建到网络请求的整个流程。
基础用法示例：
const FormData = require('./formData.js');
let formData = new FormData();
// 添加普通字段
formData.append("username", "zlyboy");
// 添加本地文件（支持多文件）
formData.appendFile("photos", "wxfile://tmp_photo1.png", "image1.png");
formData.appendFile("photos", "wxfile://tmp_photo2.png", "image2.png");
// 生成上传数据
let data = formData.getData();
wx.request({
url: 'https://your-api.com/upload',
header: {
'content-type': data.contentType
},
data: data.buffer,
method: 'POST',
success: (res) => {
console.log('上传成功', res);
}
});原创文章，作者：howkunet，如若转载，请注明出处：https://www.intoep.com/othen/73246.html
