常见文件上传 error 代码速查手册，10分钟定位并解决上传故障

原创于 2025-11-28 12:42:03 发布 · 343 阅读

6 ·

CC 4.0 BY-SA版权

第一章：文件上传 error 代码处理

在构建现代 Web 应用时，文件上传是常见功能之一，但用户在操作过程中可能遇到各种错误。正确识别并处理这些错误代码，有助于提升用户体验和系统稳定性。

常见上传错误类型

ERR_FILE_TOO_LARGE：上传文件超出服务器或客户端限制
ERR_UNSUPPORTED_TYPE：文件类型不在允许范围内
ERR_NETWORK_FAILURE：网络中断导致上传失败
ERR_UPLOAD_ABORTED：用户主动取消上传

前端错误码映射处理

通过标准化错误码，前端可统一响应逻辑。以下是一个 JavaScript 中的错误处理示例：


// 文件上传错误映射表
const UPLOAD_ERRORS = {
  1: 'ERR_FILE_TOO_LARGE',   // 超出 PHP.ini 限制
  2: 'ERR_FILE_PARTIAL',     // 文件部分上传
  3: 'ERR_NO_FILE',          // 无文件上传
  4: 'ERR_NO_FILE_SELECTED', // 用户未选择文件
  5: 'ERR_TEMP_DIR_MISSING', // 临时目录缺失
  6: 'ERR_WRITE_FAILED',     // 写入失败
  7: 'ERR_EXTENSION_BLOCKED' // 扩展阻止
};

function handleUploadError(errorCode) {
  const mappedError = UPLOAD_ERRORS[errorCode] || 'ERR_UNKNOWN';
  console.error(`上传失败: ${mappedError}`);
  return mappedError;
}

服务端返回规范

为确保前后端协同，建议使用一致的 JSON 响应结构：

字段	类型	说明
code	string	标准化错误码，如 ERR_FILE_TOO_LARGE
message	string	可读性错误描述
field	string	出错的文件字段名

graph TD A[用户选择文件] --> B{文件校验} B -->|类型/大小合法| C[发起上传] B -->|校验失败| D[返回 ERR_UNSUPPORTED_TYPE / ERR_FILE_TOO_LARGE] C --> E{服务端接收} E -->|成功| F[返回 200 + URL] E -->|失败| G[返回 error code 及 message]