在微信小程序里接入七牛云，本质上是在解决一个很现实的问题：你的图片、视频、文件该存哪里，怎么让用户流畅地访问。很多开发者一上来就照着文档配置，结果遇到上传报错、域名白名单失效、甚至存储空间被盗刷。今天咱们就把这件事彻底讲透，不光告诉你步骤，更告诉你每一步背后的坑和应对方法。

一、先搞清楚七牛在小程序里的角色分工

七牛在小程序里主要干三件事：存储文件、处理图片（比如缩略图、水印）、通过 CDN 加速分发。但小程序和普通网页有个本质区别——它不允许直接访问外链域名，所有请求都得在 request 和 uploadFile 的白名单里。很多新手第一次配置七牛，上传失败的原因就是忘了把七牛的存储域名加到小程序的 “request 合法域名” 和 “uploadFile 合法域名” 里。

举个例子，你的七牛存储空间（Bucket）是 myapp，所属区域是华东，那么上传域名应该是 https://up.qbox.me（这个域名是固定的），而下载域名是你绑定的 CDN 域名或者七牛提供的测试域名，比如 https://myapp.s3.cn-north-1.qiniucs.com。这两个域名缺一不可，而且必须在小程序后台的白名单里同时出现。

二、从零搭建上传流程：别用前端直接暴露密钥

直接在小程序里写死七牛的 AccessKey 和 SecretKey，这相当于把家门钥匙挂在门外。正确做法是：小程序端只负责选文件、传文件，而生成上传凭证（Upload Token）的工作必须交给后端。哪怕你只是个人开发者，也得在云函数或者自己的服务器上生成 token。

具体步骤拆解如下：

步骤 1：后端生成上传凭证
比如用 Node.js 写一个接口，引入七牛 SDK，代码大致是：

const qiniu = require('qiniu');
const mac = new qiniu.auth.digest.Mac('你的AccessKey', '你的SecretKey');
const options = {
  scope: '你的存储空间名',
  expires: 7200 // 凭证有效期，建议别太长
};
const putPolicy = new qiniu.rs.PutPolicy(options);
const uploadToken = putPolicy.uploadToken(mac);
// 然后把这个 token 返回给小程序

这里有个容易被忽略的细节：scope 参数可以只写 Bucket 名，也可以写成 “Bucket:key” 的形式。如果只写 Bucket 名，用户上传时可以自己指定文件名；如果写成 myapp:user_avatar/ 这种带前缀的形式，就强制用户把文件上传到指定目录下。对于社交类小程序，建议用后者，防止用户上传的文件名冲突。

步骤 2：小程序端发起上传
调用 wx.chooseImage 选择图片后，用 wx.uploadFile 把文件传给七牛：

wx.chooseImage({
  success: (res) => {
    const tempFilePaths = res.tempFilePaths[0];
    // 先请求后端获取 token
    wx.request({
      url: 'https://你的后端域名/getUploadToken',
      success: (tokenRes) => {
        const token = tokenRes.data.token;
        wx.uploadFile({
          url: 'https://up.qbox.me', // 七牛上传域名
          filePath: tempFilePaths,
          name: 'file',
          formData: {
            token: token,
            key: '用户头像/' + Date.now() + '.jpg' // 自定义文件名
          },
          success: (uploadRes) => {
            // 返回的数据里有文件的 hash 和 key
          }
        });
      }
    });
  }
});

注意这里 name: 'file' 是固定的，七牛服务器只认这个字段名。另外，上传域名 up.qbox.me 可能会因为网络环境不同而变慢，如果你的用户集中在某个区域，可以换成对应区域的加速域名，比如华东的 https://up-z0.qiniup.com，华南用 https://up-z1.qiniup.com。七牛官方文档里有一个区域域名对照表，建议存下来。

三、图片处理：不要直接返回原图给用户

很多小程序直接返回七牛的原图链接，结果一张 5MB 的照片在手机上加载半天。七牛提供了图片处理 API，可以在 URL 后面加参数实时压缩或裁剪。比如你的图片链接是 https://cdn.example.com/photo.jpg，想生成一个 200x200 的缩略图，只需在末尾加上 ?imageView2/1/w/200/h/200。

但这里有个坑：小程序里如果直接拼接这种带问号的 URL，可能会被某些版本的基础库当作非法参数。稳妥的做法是：在七牛控制台里为你的存储空间创建一个“样式”，比如定义一个叫 thumb 的样式，里面设置好裁剪尺寸，然后访问链接就变成 https://cdn.example.com/photo.jpg-thumb。这样 URL 更干净，也避免了参数被转义的问题。

另外，如果你要做图片鉴黄或者 OCR 识别，七牛也有对应的持久化处理功能。但要注意：持久化处理是异步的，需要配置回调通知，否则小程序端不知道什么时候处理完。对于实时性要求高的场景（比如用户上传头像后立刻显示），建议先用原图展示，同时触发持久化处理，等回调后再替换。

四、域名白名单与防盗链：最常见的翻车点

七牛的 CDN 域名如果没配置好，会出现“图片加载失败”或者“403 禁止访问”。微信小程序的 Webview 和 image 组件对防盗链特别敏感。七牛的默认策略是允许所有 Referer 访问，但如果你在七牛控制台里开启了“Referer 防盗链”，就必须把微信小程序的 Referer 加进去。

微信小程序的 Referer 是固定的，格式是 https://servicewechat.com/你的AppID/版本号/page-frame.html。但不同版本的微信客户端可能略有差异，最保险的做法是：在七牛防盗链设置里，把 Referer 规则设为“允许空 Referer 访问”，因为小程序在某些场景下（比如 iOS 的某些版本）不会带 Referer。同时，把微信小程序的 AppID 也加到白名单里，虽然七牛没有直接针对 AppID 的过滤，但结合空 Referer 策略就能覆盖大部分情况。

还有一个容易被忽略的点：七牛的测试域名（比如 xxx.s3.cn-north-1.qiniucs.com）是有访问额度限制的，生产环境一定要绑定自己的备案域名。而且绑定的域名必须在小程序后台的 downloadFile 合法域名列表里，否则图片下载不下来。

五、文件管理：删除和更新要留后路

小程序里经常需要用户删除自己上传的图片。七牛的对象存储没有“回收站”概念，文件一旦删除就彻底没了。所以建议在业务数据库里记录文件的 key 和上传时间，删除时先调七牛的 API 删除文件，再删数据库记录。如果误删了，七牛提供过“镜像存储”功能，可以回源到你的服务器拉取文件，但前提是你提前配置了回源规则。

另外，对于需要频繁更新的文件（比如用户头像），不要直接覆盖同一个 key。因为 CDN 缓存可能还没过期，用户看到的还是旧图。正确的做法是：每次上传新头像时，生成一个新的 key（比如加上时间戳），然后更新数据库里的头像 URL。七牛的 CDN 缓存刷新虽然可以手动操作，但总有延迟，不如从源头避免。

六、成本控制：别让一张图片花掉你几块钱

七牛按存储量、下载流量、请求次数收费。小程序里最容易超支的是“下载流量”和“图片处理次数”。比如你给用户列表里的每张图片都做了缩略图处理，如果每次请求都实时生成，七牛会按处理次数收费。解决方案是：在七牛控制台开启“图片预处理”，把缩略图提前生成好存到另一个目录，用户访问时直接拿静态文件，不触发实时处理。

还有一个省钱技巧：对于用户上传的图片，如果原图超过 1MB，在上传时就用七牛的 imageMogr2 参数自动压缩，比如 ?imageMogr2/format/webp 转成 WebP 格式，体积能减少 30%-50%。这个操作在生成上传凭证时就可以指定，不需要额外写代码。

七、调试工具：用这些方法快速定位问题

如果上传失败，先别急着看代码。打开小程序的调试工具，在 Network 面板里找到上传请求，看返回的 HTTP 状态码：

- 401：上传凭证过期或者 token 生成错误，检查后端的时间是否和七牛服务器同步（七牛要求时间差不超过 15 分钟）。
- 403：上传域名不在白名单里，或者 Bucket 权限设置为了私有。如果 Bucket 是私有的，上传时需要生成带凭证的下载链接，小程序端用 wx.downloadFile 配合 getFileURL 接口获取临时链接。
- 614：文件已存在，且你的上传策略里设置了 insertOnly 为 1。如果允许覆盖，把 insertOnly 设为 0 即可。

另外，七牛官方提供了一个 “七牛云存储 SDK 日志” 功能，可以在控制台里查看最近的上传记录和错误详情。很多开发者不知道这个入口，其实它比你自己打 log 方便得多。

八、一个完整的实战案例：用户头像上传与展示

假设你要做一个用户头像功能，要求上传后自动裁剪成 100x100 的圆形图。完整流程如下：

1. 后端生成上传凭证时，指定 key 为 avatar/用户ID_时间戳.jpg，同时设置上传回调地址（七牛上传成功后通知你的后端）。
2. 小程序端上传成功后，后端收到回调，记录文件的 key 和七牛返回的 hash。
3. 展示头像时，前端拼接 URL：https://cdn.example.com/avatar/用户ID_时间戳.jpg?imageView2/1/w/100/h/100/format/png。这里用 format/png 是为了让圆形图背景透明（如果原图是 JPG 则无法透明，所以建议强制转 PNG）。
4. 如果用户更换头像，后端先调用七牛的 delete API 删除旧文件，再重复上述流程。注意：删除操作最好异步执行，不要阻塞用户操作。

这个方案比直接前端裁剪再上传更灵活，因为七牛的图片处理参数可以随时调整，而前端裁剪会丢失原始数据。万一以后你想把头像改成 200x200，只需要改 URL 参数，不需要重新上传。

最后说一句：七牛的文档虽然详细，但很多细节散落在不同的页面里。建议把 “上传策略（PutPolicy）”、 “图片处理（imageView2）”、 “区域域名” 这三篇文档存为书签，遇到问题先翻一遍，比在网上搜零散的答案更靠谱。