移动端H5文件上传需建立团队级规范，涵盖统一入口组件、双重校验、标准化上传链路及平台兼容策略。
移动端 H5 文件上传不是“能点开、能传上去”就完事，而是要从交互入口、类型控制、预览逻辑、上传链路到错误兜底，形成可复用、可维护、可审计的一套团队级规范。核心是把经验沉淀为约束，把边界条件写进 checklist，而不是靠每次开发临时判断。
统一入口组件与 HTML 结构规范
禁止直接裸用 <input type="file">。所有上传功能必须通过封装好的 <Uploader> 组件调用，该组件需满足：
- 强制声明
accept，且值按平台细化：图片用accept="image/*"，PDF/Word 用accept=".pdf,.docx,.xlsx"（不用 MIME 类型，iOS 对application/pdf兼容差） - 移动端必须绑定真实用户点击事件触发，
click()调用不得出现在setTimeout或异步回调中 - 隐藏原生 input（
display: none），用<label>或自定义按钮包裹，确保可访问性（含for或aria-labelledby） - 预留
data-preview-target和data-upload-url等语义化属性，解耦 DOM 与业务逻辑
客户端校验与预处理双保险
前端校验不是摆设，而是第一道过滤网，必须覆盖常见绕过场景：
- 类型检查：同时比对
file.type和文件扩展名（file.name.split('.').pop().toLowerCase()），白名单严格匹配（如只允['jpg', 'jpeg', 'png', 'pdf']） - 大小限制：单文件 ≤ 10MB，批量上传总数 ≤ 10 个；超限时清空
input.value并提示“文件过大，请压缩后重试” - 图片预处理：超大图（宽或高 > 4096px）必须用 Canvas 缩放至 2048px 内再生成 Blob，避免渲染卡顿；禁用
readAsDataURL处理大图 - 非图片文件（PDF/DOCX/XLSX）仅展示图标 + 文件名 + 大小，不尝试读取内容或渲染预览
上传流程标准化与可观测性
上传不是一次 fetch，而是一条带状态、可追踪、可降级的链路：
- 统一使用
FormData构造体，append('file', file, originalName)保留原始文件名，便于后端日志定位 - 小文件（≤ 500KB）默认不显示进度条；大文件必须监听
XMLHttpRequest.upload.onprogress或使用fetch + ReadableStream实现真实进度 - 设置超时（30s）、自动重试（最多 2 次）、错误分类（网络中断 / 4xx / 5xx / 响应解析失败），每类错误对应明确用户提示文案
- 所有上传请求必须携带唯一 traceId（写入
FormData或 header），前端日志记录起止时间、文件名、大小、状态码、耗时
兼容性兜底与平台专项策略
不同平台行为差异必须硬编码适配，不能依赖“大概率可行”：
- iOS：
accept="image/*"弹照片 App；accept=".pdf"弹文件 App（需 iOS 11+）；multiple仅在 iOS 15+ 支持文档多选 - Android：
capture="environment"优先调用后置摄像头；若检测为 QQ 浏览器（/QQ\//i.test(navigator.userAgent)），强制设capture="camera"避免只弹相册 - 微信 X5 内核：禁用
capture属性时可能 fallback 到文件选择器，建议在 X5 环境下显式移除该属性 - 所有预览用的
URL.createObjectURL()必须在预览销毁或上传完成时调用URL.revokeObjectURL()，防止内存泄漏
