d8d-vite-starter/MOBILE_UPLOAD_MIGRATION.md

移动端上传改用MinIO实现迁移指南

概述

本指南记录了将移动端头像上传功能从旧的上传策略改为使用 src/client/utils/minio.ts 的完整迁移过程。

变更详情

1. 新增文件

• src/client/mobile/hooks/useAvatarUploadMinio.ts
  • 新的基于MinIO的头像上传hook
  • 使用 uploadMinIOWithPolicy 替代旧的上传策略
  • 集成图片压缩功能
  • 支持进度回调和错误处理

2. 更新文件

2.1 AvatarUpload.tsx

• 导入变更:

  • 移除 fileClient 导入
  • 添加 uploadMinIOWithPolicy 从 src/client/utils/minio

• 上传逻辑变更:

  • 使用 compressImage 进行图片压缩
  • 使用 uploadMinIOWithPolicy 上传文件
  • 简化上传流程，移除旧的多步骤上传策略

2.2 SimpleAvatarUpload.tsx

• 导入变更:

  • 从 useAvatarUpload 改为 useAvatarUploadMinio

• 使用方式:

  • 完全兼容现有API，无需其他变更

3. 测试文件

• test-mobile-avatar-upload.html
  • 移动端上传测试页面
  • 支持API连接测试、文件选择和上传测试

使用方式

新的上传hook

import { useAvatarUploadMinio } from '@/client/mobile/hooks/useAvatarUploadMinio';

const {
  isUploading,
  showCropper,
  cropImageUrl,
  uploadProgress,
  handleCropComplete,
  handleCropCancel,
  triggerFileSelect,
} = useAvatarUploadMinio({
  onSuccess: (avatarUrl) => {
    console.log('上传成功:', avatarUrl);
  },
  onError: (error) => {
    console.error('上传失败:', error);
  }
});

组件集成

所有现有组件都已更新为使用新的上传方法，无需额外配置。

优势

1. 统一的上传接口: 所有上传使用 src/client/utils/minio.ts 提供的统一接口
2. 自动分段上传: 大文件自动使用分段上传，提升上传稳定性
3. 内置压缩: 自动压缩图片，减少上传大小
4. 更好的错误处理: 提供更详细的错误信息和重试机制
5. 进度显示: 支持详细的上传进度显示

兼容性

• 完全向后兼容
• 所有现有API保持不变
• 无需修改服务端代码
• 支持所有现代浏览器

注意事项

1. 确保已配置MinIO服务端点
2. 确保文件上传路径有正确权限
3. 测试时建议使用小文件先验证功能

回滚方案

如有需要，可以快速回滚到旧版本：

1. 恢复 AvatarUpload.tsx 和 SimpleAvatarUpload.tsx 的备份
2. 恢复 useAvatarUpload 的使用
3. 删除 useAvatarUploadMinio.ts

下一步

1. 验证所有上传功能正常工作
2. 监控上传性能和质量
3. 考虑将其他文件上传功能也迁移到MinIO