小程序图片上传总失败，先别急着改代码
图片选好了，进度条却卡在一半不动；或者干脆弹出一句“上传失败”；再或者返回一串看不懂的错误码。做小程序开发的人，大概率都遇到过这类情况。更让人头疼的是，它表现得很不稳定：有时超时，有时网络错误，有时服务端返回异常，甚至同一张图在测试机上没问题，到了用户手机上就失败。碰到这种情况，先别急着动代码，按客户端、网络、服务端三个层面逐项核对配置，往往能更快找到症结。
先查客户端。第一，确认所选图片是否超过了小程序端设定的体积上限，不少上传失败其实是图片本身太大，前端还没发出去就被拦下了。第二，检查图片格式是否在允许范围内，有些接口只接受常见格式，遇到特殊格式会直接拒绝。第三，看上传接口的调用参数是否完整，比如临时文件路径、文件名、类型字段有没有漏传。第四，确认是否在用户授权之后才发起上传，授权被拒绝时上传会静默失败。第五，检查页面是否在上传过程中被销毁或切到后台，导致请求被中断。
再看网络层。小程序要求上传域名必须提前配置在后台白名单里，如果域名没加，或者只加了请求域名却漏了上传域名，真机上就会失败。同时要确认域名使用的证书是否有效、是否满足当前小程序的协议要求。还要留意用户所处的网络环境，弱网或代理环境下，大图上传更容易超时，可以适当增加超时时间并做好失败重试。
最后看服务端。检查接收接口对请求体大小是否有限制，很多服务端框架默认限制较小，稍大一点的图片就会被拒绝。确认存储路径是否可写、存储空间是否充足、权限是否正确。还要看服务端返回的错误信息是否被前端正确解析，有时服务端已经给出了具体原因，前端却统一提示“上传失败”，反而掩盖了真实问题。
有几项配置特别容易被忽略。一是上传大小限制，客户端、网关、服务端三处限制要一致，任何一处偏小都会失败。二是格式支持，不仅要看前端接受什么，还要看服务端和存储是否支持。三是域名白名单，开发阶段常用测试域名，上线前必须换成正式域名并重新配置。四是存储权限，包括临时目录、目标目录和读写权限，容器或云环境里权限问题尤其常见。
为了减少反复调试，建议在上线前做一份自测清单。用不同尺寸的图片各测一遍，覆盖小图、大图和临界值。用不同格式各测一遍，确认支持范围。在弱网、切换网络、上传中切后台等场景下各测一次。检查失败时的提示信息是否能区分网络错误、大小超限和服务端异常。确认白名单、证书和存储权限在正式环境已全部配置到位。最后模拟用户拒绝授权的情况，确认有合理的引导提示。
图片上传失败看似是小问题，背后往往牵涉多个环节的配置。把大小限制、格式支持、域名白名单和存储权限这些确认工作前置到开发阶段，而不是等到用户反馈才回头排查，能省下大量反复调试的时间。it数运在参与小程序及多端应用开发时，也习惯把这类基础配置整理成检查项，让交付过程更清晰，让问题更早暴露。技术有章法，服务有回应，很多故障其实在开发阶段就能避免。
