附件上传失败的处理

现象

上传附件时报错、一直转圈、或者上传成功后打不开。

四类原因

一、文件本身

1. 大小超限

最常见的原�因。系统通常有单文件大小限制（比如 10MB、50MB）。

排查：看错误提示，或对比成功上传的文件大小。

解决：调大限制，或压缩文件，或分片上传。

注意：调大限制要考虑：

• Web 服务器（Nginx/Apache）的 body 大小限制
• 应用框架的限制
• 反向代理的限制
• 存储空间

这几个地方都要改，只改一处还会失败。

2. 类型不支持

系统限制了允许的文件类型（比如只允许 PDF、JPG）。

排查：看文件的扩展名是否在允许列表里。

常见坑：修改扩展名伪装类型。有些系统会校验实际内容（魔数），伪装会被拒绝。

3. 文件名含特殊字符

文件名里有空格、中文、括号、特殊符号时可能出错。

解决：上传时重命名文件（用 UUID 作为文件名），原始名存在数据库里。

这也是推荐做法——既能避免特殊字符问题，也能避免重名覆盖。

4. 文件损坏

文件本身损坏，上传后无法打开。

排查：本地能打开吗？

二、网络与传输

1. 上传超时

大文件上传时间长，超过超时限制被中断。

解决：

• 调大超时
• 用分片上传（每片几 MB，失败只重传这一片）
• 显示上传进度，让用户知道在传

2. 网络不稳定

车间无线网络不稳定，上传中断。

解决：分片 + 断点续传。

3. 带宽不足

多人同时上传大文件，把带宽占满。

解决：限制并发的上传数量，或做限速。

三、服务端配置

1. 临时目录问题

上传时先写临时目录，再移动到目标位置。如果临时目录：

• 不存在
• 没有写权限
• 空间不足

就会失败。

排查：看服务端日志的报错信息。

2. 存储路径问题

目标存储目录不存在或无权限，或磁盘满了。

排查：检查磁盘空间和目录权限。

3. 反向代理限制

Nginx 有 client_max_body_size 限制，默认只有 1MB。

这是非常常见的坑：应用层调大了，Nginx 没调，上传大文件一直失败。

四、权限与业务

1. 无上传权限

用户的角色没有上传附件的权限。

2. 业务状态不允许

比如工单已关闭，不允许再上传附件。

3. 附件数量超限

单个单据限制最多传 N 个附件。

排查流程

1. 换一个小文件试（1MB 以内的图片）
   • 成功 → 大小限制问题
   • 失败 → 其他问题
2. 换一个普通文件名试（纯英文数字）
   • 成功 → 文件名特殊字符问题
3. 换一个浏览器试
   • 成功 → 浏览器兼容问题
4. 看服务端日志
   • 有明确的错误信息 → 按提示处理
5. 检查磁盘空间和权限

常见错误与处理

大文件上传的方案

如果需要传大文件（图纸、视频），建议：

"秒传"很实用：同一份图纸被多人上传时，只存一份。

安全考虑

1. 类型校验

不能只校验扩展名，要校验文件内容（魔数）。

原因：把 .exe 改名成 .jpg 就能上传，是安全隐患。

2. 存储隔离

上传的文件不要放在 Web 可执行目录下。

原因：如果上传了恶意脚本且能直接访问，会被执行。

解决：存到 Web 根目录之外，通过接口鉴权后读取。

3. 病毒扫描

如果开放上传，建议加病毒扫描（尤其是外部用户可上传的场景）。

4. 访问控制

附件的下载链接要有权限校验。不能用一个可猜测的 URL 就能下载。

常见问题：附件 URL 是 /files/123.pdf，改个数字就能下载别人的附件。

预防措施

• 前端显示上传进度，避免用户以为卡死而重复上传
• 明确提示大小和类型限制，不要让用户上传完才知道不支持
• 上传失败给明确的错误原因，不要只提示"上传失败"
• Nginx 和应用层限制保持一致
• 定期清理无用附件（上传中途取消产生的临时文件）

上传限制与存储配置，[待补充：百华智造 MES 附件存储配置说明]。