1. 为什么要在小程序里折腾文件上传

做过微信小程序的人都有一个共识：原生组件够用，但不够好用。尤其是文件上传这种高频交互场景，原生wx.chooseMedia加上wx.uploadFile的组合，写起来不难，但要把交互体验做顺滑，得自己手搓一整套 UI 和状态管理。我最早做小程序表单的时候，就是硬写了一套上传组件，结果光是缩略图预览、删除按钮、上传进度、失败重试这几个状态就把代码搞得又臭又长，后来维护起来非常痛苦。

Vant Weapp 的uploader组件就是来解决这个问题的。它是 Vant 组件库在小程序端的实现之一，专门处理图片和文件的选择、预览、上传、删除这一整条链路。你只需要在wxml里写一个<van-uploader>标签，配合几个属性和事件回调，就能得到一个体验接近原生 App 的上传控件。这篇文章我会把我在实际项目里用这个组件的完整过程拆开讲，包括环境搭建、核心属性配置、上传逻辑实现、后端对接、踩过的坑，以及一些官方文档里不会写的细节。

适合谁看？如果你正在做微信小程序，需要处理用户头像上传、证件照提交、多图晒单、表单附件这类需求，那这篇内容基本可以当参考手册用。如果你还没接触过 Vant Weapp，也没关系，我会从安装配置开始讲，保证你能跟着跑通。

核心关键词先摆出来：微信小程序、Vant Weapp、uploader 组件、文件上传、图片预览、上传进度、表单校验。这几个词贯穿全文，你可以在阅读时留意它们出现的上下文。

2. 环境准备与 Vant Weapp 接入

2.1 小程序项目初始化与 npm 支持

Vant Weapp 是通过 npm 包的方式引入的，所以第一步得确保你的小程序项目开启了 npm 支持。如果你用的是微信开发者工具，新建项目后，在项目根目录下执行npm init -y生成package.json，然后安装依赖：

npm install @vant/weapp --save

装完之后，在微信开发者工具的菜单栏找到「工具」→「构建 npm」，点击后工具会把node_modules里的包编译到miniprogram_npm目录。这一步很多人第一次做会漏掉，结果usingComponents引用了组件却一直报「组件未找到」。记住：每次安装或更新 npm 包后，都要重新构建一次。

构建完成后，你会在项目里看到miniprogram_npm/@vant/weapp这个目录，说明组件已经就绪。

2.2 全局引入与按需引入的取舍

Vant Weapp 支持两种引入方式。一种是在app.json里全局注册，比如：

{ "usingComponents": { "van-uploader": "@vant/weapp/uploader/index" } }

另一种是在具体页面的json文件里按需引入。我的建议是：如果只有一两个页面用到上传，就按需引入；如果多个页面都有上传需求，再考虑全局注册。全局注册会让每个页面都加载组件代码，虽然 Vant 做了分包优化，但没必要的开销还是能省则省。

这里有个细节：uploader组件内部依赖了van-icon、van-image等子组件，Vant 的 npm 包已经处理好了依赖关系，你不需要手动一个个注册，只要引入uploader就行。

2.3 基础样式与主题定制

Vant Weapp 的样式默认跟随微信小程序的rpx单位，适配性不错。但如果你项目里有自己的设计规范，比如主色调不是 Vant 默认的蓝色，可以通过 CSS 变量覆盖。在app.wxss里加上：

page { --uploader-icon-color: #07c160; --uploader-border-color: #ebedf0; }

Vant Weapp 的 CSS 变量命名有规律，一般以--组件名-属性的形式出现。你可以在官方文档的「定制主题」章节查到完整列表。我一般只改几个关键颜色，改太多反而容易和后续版本升级冲突。

提示：CSS 变量的作用域遵循小程序的样式规则，定义在page上可以全局生效，定义在具体页面的wxss里则只对该页面有效。

3. uploader 组件的核心属性拆解

3.1 文件选择与数量控制

uploader最核心的属性是file-list，它是一个数组，每一项代表一个已选文件。组件本身不管理文件状态，所有状态都由你通过file-list传入，并通过bind:after-read、bind:delete等事件回调来更新。这种「受控组件」的设计模式在 React 里很常见，小程序里用起来也不复杂，但新手容易犯一个错：在事件回调里直接修改file-list数组而不触发setData，导致视图不更新。

正确的做法是每次操作后都重新setData整个数组，或者用this.setData({ 'fileList[0].url': newUrl })这种路径写法精确更新。

控制上传数量的属性是max-count，默认是 52，基本等于不限。实际项目里我一般设成 1（头像）、3（晒单）、6（证件照）这种具体数字。当达到上限时，上传按钮会自动隐藏，这个交互很自然，不需要你额外写逻辑。

还有一个multiple属性，设为true时允许一次选多张。注意这个属性只在wx.chooseMedia支持多选的场景下生效，且max-count会限制总数量。

3.2 上传前的图片处理策略

uploader提供了几个和图片处理相关的属性，我挑最实用的说。

size-type控制返回图片的尺寸，默认是['original', 'compressed']，意思是优先返回原图，原图过大时返回压缩图。如果你做的是头像上传，建议改成['compressed']，因为头像显示区域就那么大，原图纯属浪费带宽和存储。

preview-size控制预览图的大小，默认是['90px', '90px']。这个值影响的是缩略图在页面上的显示尺寸，不是上传图片的实际尺寸。我见过有人把它和size-type搞混，以为改了preview-size就能压缩上传图片，结果上传的还是原图。

deletable属性控制是否显示删除按钮，默认true。如果你做的是只读展示场景，比如订单详情里展示用户已上传的凭证，就把它设为false。

3.3 上传状态与进度反馈

uploader的file-list里每一项可以包含status字段，取值有uploading、done、failed。组件会根据这个状态显示不同的 UI：上传中显示进度圈，成功显示对勾，失败显示感叹号。这个状态需要你在上传逻辑里手动维护。

status为uploading时，还可以设置message字段显示进度文字，比如「50%」。不过实际用下来，进度圈本身已经够直观了，文字反而显得冗余，我一般只在文件较大、上传时间较长时才加。

bind:after-read是文件选择完成后的回调，参数里包含file对象，里面有url（本地临时路径）、size、name等信息。你在这个回调里发起上传请求，并更新file-list的状态。

4. 完整上传流程的代码实现

4.1 页面结构与数据定义

先看wxml结构，这是最直观的部分：

<van-uploader file-list="{{ fileList }}" max-count="3" bind:after-read="onAfterRead" bind:delete="onDelete" bind:click-preview="onPreview" size-type="{{ ['compressed'] }}" />

然后在页面的js里定义初始数据：

Page({ data: { fileList: [] }, onAfterRead(event) { const { file } = event.detail; // file 是一个对象或对象数组，取决于 multiple 属性 const files = Array.isArray(file) ? file : [file]; // 先更新状态为上传中 const newList = this.data.fileList.concat( files.map(f => ({ ...f, status: 'uploading', message: '上传中' })) ); this.setData({ fileList: newList }); // 逐个上传 files.forEach((f, index) => { this.uploadFile(f, this.data.fileList.length - files.length + index); }); } });

这里有个细节：after-read的file参数在单选时是对象，多选时是数组。我一开始没注意，直接当对象用，结果多选场景下file.url是undefined，排查了半天。所以上面代码里用Array.isArray做了兼容。

4.2 上传请求的封装与进度监听

微信小程序的wx.uploadFile支持onProgressUpdate回调，可以拿到上传进度。我把它封装成一个 Promise：

uploadFile(file, index) { const that = this; const uploadTask = wx.uploadFile({ url: 'https://your-domain.com/api/upload', filePath: file.url, name: 'file', formData: { token: wx.getStorageSync('token') || '' }, success(res) { const data = JSON.parse(res.data); if (data.code === 0) { that.setData({ [`fileList[${index}].status`]: 'done', [`fileList[${index}].url`]: data.data.url, [`fileList[${index}].message`]: '' }); } else { that.setData({ [`fileList[${index}].status`]: 'failed', [`fileList[${index}].message`]: '上传失败' }); } }, fail() { that.setData({ [`fileList[${index}].status`]: 'failed', [`fileList[${index}].message`]: '网络异常' }); } }); uploadTask.onProgressUpdate((res) => { that.setData({ [`fileList[${index}].message`]: res.progress + '%' }); }); }

注意wx.uploadFile返回的是一个UploadTask对象，你可以调用它的abort()方法取消上传。这个在用户快速删除文件时很有用，避免无效请求占用带宽。

提示：wx.uploadFile的success回调里，res.data是字符串，需要手动JSON.parse。如果后端返回的不是标准 JSON，解析会报错，建议加try-catch。

4.3 删除与预览的联动处理

删除逻辑相对简单，但有个坑：bind:delete事件的参数里包含index，你根据这个索引从file-list里移除对应项即可。但如果文件正在上传中，最好先调用abort()取消请求，再移除。

onDelete(event) { const { index } = event.detail; const file = this.data.fileList[index]; if (file.status === 'uploading' && file.task) { file.task.abort(); } const newList = this.data.fileList.filter((_, i) => i !== index); this.setData({ fileList: newList }); }

预览用的是wx.previewImage，bind:click-preview事件会返回当前点击的index和file。你可以把file-list里所有status为done的url收集起来，传给wx.previewImage的urls参数，这样用户左右滑动就能切换预览。

onPreview(event) { const { index } = event.detail; const urls = this.data.fileList .filter(f => f.status === 'done') .map(f => f.url); wx.previewImage({ current: urls[index], urls: urls }); }

这里要注意：urls数组的顺序要和file-list里done状态的顺序一致，否则current指向的图片会错位。我一般会在过滤后重新计算index，确保预览的是用户点击的那张。

5. 后端对接与安全校验

5.1 上传接口的字段约定

wx.uploadFile发送的是multipart/form-data请求，后端接收时要注意字段名。name属性指定了文件字段的名称，默认是file，你可以改成后端约定的任何名字。formData里的字段会作为额外的表单字段一起发送，适合传 token、业务 ID 这类参数。

后端返回的格式建议统一成{ code, message, data }的结构，data里包含文件的访问 URL。这样前端处理起来逻辑清晰，成功就更新url，失败就标记failed。

5.2 文件类型与大小限制

uploader组件本身不限制文件类型，它调用的是wx.chooseMedia，默认只能选图片和视频。如果你需要上传 PDF、Word 这类文档，得用wx.chooseMessageFile，但uploader不直接支持，需要你自己封装一个类似的上传控件。

图片大小限制可以在after-read回调里做：

onAfterRead(event) { const { file } = event.detail; const files = Array.isArray(file) ? file : [file]; const maxSize = 5 * 1024 * 1024; // 5MB const validFiles = files.filter(f => { if (f.size > maxSize) { wx.showToast({ title: '图片不能超过5MB', icon: 'none' }); return false; } return true; }); if (validFiles.length === 0) return; // 继续上传逻辑 }

这里有个体验细节：如果用户选了 3 张图，其中 1 张超限，你是全部拒绝还是只拒绝超限的那张？我倾向于只拒绝超限的，把合规的继续上传，并在 toast 里说明「1 张图片超过大小限制，已忽略」。这样用户不用重新选一遍。

5.3 上传接口的鉴权与防重

小程序的上传接口一般需要携带登录态。我通常把 token 放在formData里，后端在接收文件前先校验 token。注意wx.uploadFile的header里也可以放 token，但有些后端框架对multipart请求的 header 解析有差异，放formData更稳妥。

防重方面，可以在前端生成一个唯一 ID，比如时间戳加随机数，作为formData的一个字段传给后端。后端根据这个 ID 做幂等处理，避免用户快速点击导致重复上传。虽然uploader在达到max-count后会隐藏按钮，但网络延迟场景下用户仍可能重复触发。

6. 常见问题与排查技巧实录

6.1 上传后图片不显示或显示裂图

这是最常见的问题，原因通常有三个。第一，file-list里的url没有更新成后端返回的正式地址，还是本地临时路径。本地临时路径在小程序重启后会失效，所以上传成功后必须替换成服务器地址。第二，后端返回的 URL 是相对路径，前端直接拿来用，但van-image需要完整 URL。第三，图片服务器做了防盗链，小程序的referer不在白名单里，导致图片加载失败。

排查方法：在success回调里console.log一下data.data.url，确认是完整地址；然后在开发者工具的「网络」面板看图片请求的响应状态码，403 就是防盗链问题。

6.2 上传进度不更新或卡在 0%

onProgressUpdate回调不触发，通常是因为wx.uploadFile的success回调执行太快，进度还没来得及更新就完成了。小文件上传时这是正常现象，不用管。如果大文件也卡在 0%，检查一下uploadTask是否被正确引用，以及setData的路径写法是否正确。

另一个可能：你在after-read里用了async/await，但wx.uploadFile是回调式的，没有正确返回 Promise，导致uploadTask变量作用域丢失。建议把上传逻辑封装成独立的函数，确保uploadTask在闭包里可访问。

6.3 多选时 file-list 顺序错乱

after-read返回的file数组顺序和用户选择顺序一致，但如果你用Promise.all并发上传，完成顺序可能不同，导致file-list里的顺序和用户预期不符。解决办法是上传前先按选择顺序把文件插入file-list，上传完成后只更新对应索引的status和url，不改变数组顺序。

6.4 常见问题速查表

6.5 几个我踩过的坑

第一个坑：在after-read里直接this.data.fileList.push(file)，然后this.setData({ fileList: this.data.fileList })。这种写法在小程序里不会触发视图更新，因为setData比较的是引用地址，数组引用没变。正确做法是concat或扩展运算符生成新数组。

第二个坑：size-type设成['compressed']后，部分安卓机型返回的压缩图质量很差，文字都糊了。后来改成['original', 'compressed']，让微信根据图片大小自动选择，效果好很多。

第三个坑：上传接口的url用了http而不是https，在开发者工具里能跑，真机上直接失败。小程序要求所有网络请求必须走https，这个在开发阶段很容易忽略。

第四个坑：file-list里的name字段我一开始没填，结果后端接收到的文件名是随机字符串。后来在after-read里手动给每个文件加上name: 'image_' + Date.now() + '.jpg'，后端就能按业务规则命名了。

7. 进阶玩法与性能优化

7.1 自定义上传按钮样式

uploader默认的上传按钮是一个灰色虚线框加一个加号图标。如果你想让按钮更符合品牌调性，可以用slot自定义。在wxml里：

<van-uploader file-list="{{ fileList }}" bind:after-read="onAfterRead"> <view class="custom-upload-btn"> <van-icon name="plus" size="24px" /> <text>添加图片</text> </view> </van-uploader>

然后在wxss里给.custom-upload-btn写样式。注意自定义 slot 后，max-count达到上限时按钮不会自动隐藏，需要你自己在wxml里加wx:if判断。

7.2 大文件分片上传的思路

wx.uploadFile不支持分片上传，如果业务场景需要上传几十兆的视频，得用wx.request配合ArrayBuffer手动分片。思路是把文件切成固定大小的块，逐块上传，后端合并。这个实现复杂度较高，一般项目用不到，但如果你做的是教育类小程序，需要上传课程视频，就得考虑这个方案。

分片上传的关键是记录每片的偏移量和总分片数，后端按顺序拼接。前端可以用wx.getFileSystemManager().readFile读取文件的指定区间，转成ArrayBuffer后通过wx.request发送。

7.3 上传队列与并发控制

默认情况下，用户选了几张图就会并发发起几个上传请求。如果图片较多，并发请求会占用大量带宽，导致每张图的上传速度都很慢。我一般会限制并发数为 2 到 3，用一个简单的队列来控制：

const queue = []; let uploading = 0; const MAX_CONCURRENT = 2; function enqueue(task) { queue.push(task); next(); } function next() { while (uploading < MAX_CONCURRENT && queue.length > 0) { const task = queue.shift(); uploading++; task().finally(() => { uploading--; next(); }); } }

这样用户体验会好很多，进度条也能更平滑地更新。

7.4 图片压缩与格式转换

小程序端做图片压缩，可以用wx.compressImage，但它只支持jpg格式，且压缩质量参数在部分机型上不生效。更稳妥的方案是在after-read里用canvas手动绘制压缩，但代码量较大。我的经验是：如果后端有图片处理服务，前端直接传原图，让后端压缩和转格式，这样前端逻辑最简单，也最可靠。

如果非要在前端压缩，建议把size-type设为['compressed']，微信会在选择阶段就返回压缩图，省去自己处理的麻烦。实测下来，压缩后的图片体积能减少 60% 到 80%，对于大多数展示场景足够用了。

8. 一些个人体会

这个组件我从两年前开始用，中间经历过几次大版本升级，整体稳定性不错。Vant Weapp 的维护团队更新频率挺高，遇到问题去 GitHub 的 issue 区搜一下，基本都能找到答案。我印象比较深的一次是某个版本升级后after-read的参数结构变了，从event.detail.file变成了event.detail.file加event.detail.index，当时没看更新日志，排查了好一会儿。所以我的建议是：升级组件库之前，先扫一眼 changelog，尤其是大版本号变动时。

另外，uploader虽然好用，但它不是万能的。如果你的上传需求涉及非图片文件、分片上传、断点续传，那它可能不是最佳选择，自己封装一个反而更灵活。工具是拿来解决问题的，不是拿来供着的，选型时想清楚自己的核心场景最重要。

最后分享一个小技巧：在file-list里给每个文件加一个uid字段，用时间戳加随机数生成。这样在删除、预览、重试时，用uid来定位文件比用index更可靠，尤其是在并发上传和动态排序的场景下，能避免很多索引错乱的问题。这个字段后端不需要，纯粹是前端用来做状态管理的，但非常实用。