别让用户传图把你服务器撑爆：vibe 项目的文件上传实战

几乎每个 vibe coding 项目都会走到这一步：用户要传头像、传图片、传附件。AI 三分钟给你生成一个“能跑”的上传接口，你点一点，图传上去了，皆大欢喜。然后上线第三周，第一个用户传了 200 张手机原图，你的服务器磁盘报警了；第五周，有人在你评论区贴了一张“图片”，点开却执行了脚本。这篇指南，就是写给那个时刻之前的你。

文件上传看起来是个 CRUD 边角料，实际上它是个人项目里翻车率最高的功能之一：流量、存储、安全、成本，四条线拧在一起。下面七个小节，每一节先给一个明确的立场，再讲为什么和怎么做。

第一天就上直传，别让流量过你的服务器

AI 默认给你写的上传链路是这样的：前端 FormData → POST /api/upload → 你的服务器收下整个文件 → 再转存到 S3/R2。Demo 阶段没问题，但这条链路的账是这么算的：100 个用户，每人传 5 张手机原图，每张 8MB，就是 4GB 流量先经过你的服务器内存和磁盘，再原样转出去一遍。Vercel Hobby 的 serverless 函数请求体上限 4.5MB，超了直接 413；Railway/Render 上 512MB 内存的小实例，几个并发上传就能把内存吃光；磁盘更惨，4GB 的小盘传两轮就满。

判断很简单：第一天就上直传，别走服务器中转。正确姿势是 presigned URL：前端先向你的 API 要一张“一次性上传凭证”——GET /api/uploads/sign 返回 { uploadUrl, objectKey }；前端拿着这个 URL 直接 PUT 到对象存储，文件一滴都不经过你的服务器；传完后前端回调 POST /api/uploads/confirm，服务端校验文件确实存在、大小和类型合规，再写入数据库。

这么做有三个赢面：第一，服务器内存和磁盘零压力，上传 10GB 的视频你的 Node 进程都感觉不到；第二，天然绕过 serverless 的请求体上限；第三，横向扩展时不用操心上传节点的亲和性。代价也有一个：你要自己处理“传了但没确认”的孤儿文件——这个放在第六节讲。

选型上，个人项目我直接推荐 Cloudflare R2：S3 兼容 API，aws-sdk 零改动就能接，存储 $0.015/GB·月，关键是出口流量 $0。如果你已经在用 AWS 全家桶，S3 presigned URL 同样成熟。别自己搭 MinIO，除非你有运维瘾——vibe 项目的第一原则，是把运维外包出去。

图片的黄金链条：浏览器先压，服务端再转格式

手机拍一张照片，8MB 起步，iPhone ProRAW 能到 25MB。你要是原图直存，列表页一次加载 30 张缩略图，用户流量直接爆炸，CDN 账单跟着爆炸。立场：压缩做两层，浏览器端是第一道防线。

第一层在浏览器：用用户自己的 CPU 做压缩，免费。用 browser-image-compression 这类库，选图后先压到 1600px 长边、WebP 质量 0.8，一张 8MB 的原图通常能压到 300~500KB，体积缩小 90% 以上再上传。注意要在前端就做，别等传到服务端——省的是你的流量钱和用户的时间。

第二层在服务端：收到文件后用 sharp 统一转码。为什么还要转一次？因为浏览器端不可信：用户可能绕过你的前端直接调接口。服务端转码即清洗——能被 sharp 正常 decode 并输出的，才是一张真图。格式上，列表缩略图用 WebP（比 JPEG 小 25~35%），大图可以考虑 AVIF（再省 20%，但编码慢 5~10 倍，慎用在请求链路上，适合丢进离线任务队列里转）。

一个数字给你信心：1600px、WebP q80 这组“黄金参数”，在 1080p 手机屏上肉眼几乎看不出区别，文件却只有原图的 5%。这笔买卖不做，等于把钱烧给 CDN。

安全：上传接口是你服务器上张开最大的嘴

判断先行：文件上传是整个后端最大的攻击面，没有之一。登录接口好歹还有密码学撑腰，上传接口面对的可是任意二进制。

第一，永远别信扩展名和 Content-Type——那都是用户“自称”的。把 evil.php 改名 evil.jpg 上传，是 2005 年的老梗，2026 年依然有人中招。只看魔数（file signature）：FF D8 FF 开头才是 JPEG，89 50 4E 47 开头才是 PNG。用 file-type 库读文件头判定，扩展名只做展示用。

第二，SVG 不是图片，是披着图片外衣的网页。SVG 里可以内嵌 <script>，你把它当 <img> 展示没事，可一旦某处用了 innerHTML、或者用户能拿到原文件 URL 直接访问，就是存储型 XSS。立场：用户上传的 SVG，一律拒绝；非要支持，就转成 PNG 光栅化，别整沙箱域名那套——个人项目玩不起。

第三，zip 炸弹：42KB 的 42.zip 解压后是 4.5PB。凡是服务端要解压用户上传的压缩包，立场：流式解压、边读边计数，解压后总大小和文件数设硬上限（比如 100MB / 1000 个文件），超了直接丢弃。

第四，文件名永远别用用户传的。存储 key 必须服务端生成：uuid + 从魔数推导出的扩展名。这防的是路径遍历（../../etc/passwd）和特殊字符炸弹。用户原来的文件名可以存进数据库做展示，但绝不进文件系统。

第五，上传目录不可执行，是上古 PHP 时代的血泪。用对象存储直传，这个问题天然消失——这是直传架构附赠的安全红利，支持直传的理由又多了一条。

大小限制与分片上传：断点续传是给弱网准备的

先立个判断：分片上传不是为“大文件”准备的，是为“烂网络”准备的。用户在地铁里用 4G 传 50MB 视频，单次 PUT 的失败率高得离谱；分片之后，失败只重传 5MB 的一片，体验天差地别。

限制要分三层设：网关层（Nginx client_max_body_size、Cloudflare 100MB、Vercel 4.5MB——先搞清楚你的天花板）；应用层（按业务设，比如头像 5MB、附件 50MB，超了前端在选文件时就拦，别等传完再告诉用户不行）；存储层（bucket policy 或签名时限定 content-length-range，让对象存储帮你挡）。

分片实现直接用 S3 multipart 语义：5MB 一片，并发 3~4 片上传，全部完成后再 Complete。R2 同样兼容这套 API。前端选完文件先算 SHA-256：哈希相同直接秒传，还能天然去重——同一个文件全站只存一份，存储账又省一笔。

最后，进度条不是装饰品。没有 onUploadProgress 反馈的上传页，用户会狂点重试，制造一堆重复文件和重复请求。把进度、速度、剩余时间都给他，他才不会捣乱。

访问加速与存储成本：算一笔三年的账

个人项目死于账单的不少，文件存储是重灾区。先看单价：S3 Standard 存储 $0.023/GB·月，出口 $0.09/GB；Cloudflare R2 存储 $0.015/GB·月，出口 $0；Backblaze B2 存储 $0.006/GB·月，出口每天前 1GB 免费、之后 $0.01/GB。

算个账：一个相册类应用，存 100GB 图片，每月产生 500GB 图片流量。S3：2.3 + 45 = $47.3/月；R2：$1.5/月。差 30 倍，一年差 $550。这就是立场：个人项目选 R2，零出口费是送给独立开发者的礼物。但别把鸡蛋放一个篮子：域名和 DNS 别全绑在同一家，迁移时只换 CNAME 就能走。

访问加速：图片一律走 CDN，别让用户直连对象存储源站。URL 上带尺寸参数做动态裁剪（/cdn-cgi/image/width=400/xxx.webp 这类），列表页用小图、详情页用大图——同一张原图、多种尺寸，源站只存一份。CDN 缓存命中率做到 90% 以上，回源流量才降得下来。

还有个省钱的冷知识：缩略图和原图分 bucket（或前缀）存，缩略图设短缓存、原图设长缓存；不常访问的冷数据丢到低频存储层。vibe 项目早期用不上，但架构上留好前缀规划，半年后你会感谢自己。

删除与孤儿文件清理：上传只是半条命

判断：没有删除键的上传功能是半成品，没有孤儿清理的存储是漏水的水桶。

删除要做成两段：用户点删除 → 数据库软删除、文件移入 trash/ 前缀 → 7 天后定时任务真删。为什么折腾？一是给用户“后悔药”，二是客服纠纷时有据可查，三是避免“删记录成功、删文件失败”的数据不一致。顺序也有讲究：覆盖上传时，先写新 key、确认成功，再删旧文件——反过来一次失败，用户的头像就变成空白了。

孤儿文件是这么来的：用户选了图、传上去了，但表单没点保存；或者后端校验失败、DB 回滚了，文件却留在了存储里。三个月下来，存储里 30% 可能是没人认领的垃圾。立场：孤儿清理必须是个每天跑的定时任务，不是可选项。逻辑很简单：扫存储里的 key 列表，反查数据库，没有引用的移入 trash，30 天后真删。第一次跑先 dry-run，看着数量别手抖。

再补一条：给每个用户配上传配额。免费用户 1GB、付费 100GB，超了就提示升级。配额是最便宜的防刷手段——有人拿你的上传接口当免费图床时，你会庆幸早就加了。

上线前验收清单：逐项打勾再发布

下面这份清单建议保存下来，每次改上传逻辑都跑一遍：

1. 传 10MB、50MB、200MB 三个量级各一遍；开发工具里把网络限速成 3G，验证断点续传可用
2. 把 evil.exe 改名 evil.jpg 上传，看魔数校验能不能拦下
3. 传一个带 <script> 的 SVG，确认被拒绝或光栅化
4. 文件名填 ../../etc/passwd，看存储 key 是否还是服务端生成的 UUID
5. 传完删一次：数据库软删除、7 天后存储里真没了
6. 孤儿清理任务 dry-run 跑一轮，看数量级是否合理
7. 列表页 30 张图，CDN 缓存命中率是否大于 90%
8. 速率限制生效：同一 IP 1 分钟 20 次上传，超了返回 429
9. 账单告警开了：R2/S3 的 budget alert，别等月底傻眼
10. 手机 Safari/Chrome 各传一遍——iOS 的 HEIC 格式会教你做人（服务端用 sharp 转掉，或前端先转 JPEG）

最后说一句：AI 能帮你写出“能跑”的上传功能，但“跑不坏”的版本，得你亲手把上面这七个坑想一遍。文件上传这事，架构选对（直传）、压缩做狠（两层）、安全做绝（魔数加拒 SVG）、账算清（R2 加 CDN）、尾巴收好（删除加孤儿清理），基本就稳了。剩下的，就是等用户传第一张图上来，然后盯着监控喝杯咖啡。