Antd Upload组件上传时未触发接口请求

Question

使用 Ant Design 的 Upload 组件时，常见问题之一是点击上传后未触发接口请求。该问题通常由 `action` 属性未正确设置或 `customRequest` 被覆盖但未实现导致。若设置了 `beforeUpload` 返回 `false`，会阻止默认上传行为且不发起请求，需确保其返回值允许上传继续。此外，当使用受控模式（fileList）时，若未正确更新文件状态，也可能使组件误判上传流程已完成，从而不触发请求。

Answer 1

1. Ant Design Upload 组件上传未触发请求的常见现象

在使用 Ant Design 的 <Upload> 组件时，开发者常遇到点击“上传”按钮后，浏览器未发出任何网络请求的问题。该问题表面表现为“无响应”，但实际背后涉及多个潜在原因，包括配置缺失、生命周期钩子误用以及状态管理不当等。

• 用户点击“上传”后，控制台无任何错误提示
• Network 面板中未出现预期的文件上传请求
• 组件 UI 显示“正在上传”，但进度条卡住不动
• fileList 状态看似已更新，但接口从未调用

2. 核心机制解析：Upload 组件如何发起请求

Ant Design 的 Upload 组件默认通过以下流程触发上传：

1. 用户选择文件后，组件调用 beforeUpload 钩子进行前置校验
2. 若 beforeUpload 返回 false 或 Promise.reject()，则中断上传流程
3. 若返回 true 或不返回值，则继续执行默认上传逻辑
4. 默认上传行为依赖 action 属性指定的目标 URL 发起 POST 请求
5. 若设置了 customRequest，则完全接管上传逻辑，需手动实现请求发送

3. 常见问题排查路径与解决方案

问题原因	表现特征	解决方案
action 未设置或为空字符串	无任何请求发出	确保 action 指向有效接口地址
customRequest 被覆盖但未实现	组件不报错但不上传	提供完整的 customRequest 函数实现
beforeUpload 返回 false	阻止上传且无提示	检查条件逻辑，仅在需要拦截时返回 false
受控模式下 fileList 状态未正确更新	组件认为已上传完成	在上传开始时将文件 status 设为 'uploading'

4. 实际代码示例：正确配置 Upload 组件

import { Upload, message } from 'antd';
import { UploadOutlined } from '@ant-design/icons';

const MyUploadComponent = () => {
  const handleBeforeUpload = (file) => {
    const isLt2M = file.size / 1024 / 1024 < 2;
    if (!isLt2M) {
      message.error('文件大小不能超过 2MB!');
    }
    // 必须返回 true 或 undefined 才能继续上传
    return isLt2M || Upload.LIST_IGNORE;
  };

  const handleChange = ({ fileList }) => {
    // 受控模式必须通过 state 更新 fileList
    setFileList(fileList);
  };

  return (
    <Upload
      action="/api/upload"
      beforeUpload={handleBeforeUpload}
      onChange={handleChange}
      fileList={fileList}
    >
      <button type="button"><UploadOutlined /> 上传文件</button>
    </Upload>
  );
};
    

5. 自定义上传逻辑（customRequest）的完整实现

当需要精细化控制上传过程（如添加 token、进度监听、断点续传）时，应使用 customRequest：

const customRequest = async ({ file, onProgress, onSuccess, onError }) => {
  const formData = new FormData();
  formData.append('file', file);

  try {
    const response = await fetch('/api/upload', {
      method: 'POST',
      body: formData,
      onUploadProgress: (progressEvent) => {
        const percent = Math.round((progressEvent.loaded * 100) / progressEvent.total);
        onProgress({ percent });
      },
    });

    if (response.ok) {
      const result = await response.json();
      onSuccess(result);
    } else {
      throw new Error('上传失败');
    }
  } catch (error) {
    onError(error);
  }
};

// 使用方式
<Upload customRequest={customRequest} ... />
    

6. 受控模式下的状态同步陷阱

在使用 fileList 进行受控管理时，若未显式设置文件的 status，组件可能误判文件状态。例如：

• 初始添加文件时，status 应为 undefined 或 ready
• 上传开始前，应将其设为 'uploading'
• 成功后设为 'done'，失败则为 'error'

错误示例：

// ❌ 错误：未设置 uploading 状态
onChange = ({ file, fileList }) => {
  if (file.status === 'uploading') {
    setFileList(fileList); // 此时状态未被正确识别
  }
}
    

正确做法：

onChange = ({ file, fileList }) => {
  if (file.status === 'uploading') {
    // 显式标记为上传中
    file.status = 'uploading';
  }
  setFileList([...fileList]);
}
    

7. 流程图：Upload 组件上传决策流程

graph TD
            A[用户选择文件] --> B{beforeUpload 存在?}
            B -->|是| C[执行 beforeUpload]
            C --> D{返回 false 或 reject?}
            D -->|是| E[终止上传]
            D -->|否| F{customRequest 是否设置?}
            F -->|是| G[调用 customRequest]
            F -->|否| H{action 是否有效?}
            H -->|是| I[发起默认上传请求]
            H -->|否| J[静默失败]
            G --> K[自定义请求处理]
            I --> L[更新 fileList 状态]
            K --> L
            L --> M[上传完成]

8. 高级调试技巧与生产建议

对于具备 5 年以上经验的开发者，可从架构层面优化上传模块：

• 封装通用 Upload 组件，内置重试机制、限速、并发控制
• 结合 Redux 或 Zustand 管理全局上传任务队列
• 利用 transformFile 在上传前进行压缩或格式转换
• 通过 directory 支持文件夹上传，并递归处理
• 集成 Sentry 或类似工具捕获上传异常并上报
• 使用 Web Workers 处理大文件分片计算，避免主线程阻塞