OSS_IMPLEMENTATION.md•2.89 kB
# 阿里云OSS上传功能实现总结
## 功能概述
实现了完整的阿里云OSS文件上传功能，包括：
- 临时上传凭证获取
- 直接上传到OSS
- 上传进度跟踪
- 状态管理
- 错误处理和重试机制
## 文件结构
### 1. API路由 (`/api/assets/oss/route.ts`)
- **POST方法**: 获取OSS临时上传凭证
- **GET方法**: 处理上传完成后的回调
### 2. 工具函数 (`/lib/utils.ts`)
- `uploadToOSS()`: 基础OSS上传函数
- `uploadToOSSWithProgress()`: 带进度跟踪的OSS上传函数
- `getOSSFileUrl()`: 获取OSS文件完整URL
### 3. 组件更新
- `FormFileUpload`: 文件上传组件，支持多文件上传和进度显示
- `SuggestionDialog`: 建议对话框，支持附件上传
- `SubmitPage`: 应用提交页面，支持Logo上传
### 4. 测试页面
- `/test-upload`: OSS上传功能测试页面
## 核心功能
### 上传流程
1. **获取临时凭证**: 前端调用POST `/api/assets/oss` 获取临时上传URL
2. **直接上传**: 使用临时URL直接上传文件到OSS
3. **回调通知**: 上传完成后调用GET `/api/assets/oss` 通知服务器
### 状态管理
- `idle`: 初始状态
- `uploading`: 上传中，显示进度
- `success`: 上传成功
- `error`: 上传失败，支持重试
### 安全特性
- 临时上传凭证，有效期15分钟
- 文件类型和大小验证
- 唯一文件名生成
- 参数验证和错误处理
## 环境配置
在 `.env.local` 中配置：
```bash
ALIYUN_OSS_REGION=oss-cn-hangzhou
ALIYUN_ACCESS_KEY_ID=your_access_key_id
ALIYUN_ACCESS_KEY_SECRET=your_access_key_secret
ALIYUN_OSS_BUCKET=your_bucket_name
```
## 使用示例
### 基础使用
```typescript
import { uploadToOSS } from "@/lib/utils";
const result = await uploadToOSS(file, "app-logos");
if (result.success) {
console.log("上传成功:", result.url);
}
```
### 带进度跟踪
```typescript
import { uploadToOSSWithProgress } from "@/lib/utils";
const result = await uploadToOSSWithProgress(file, "app-logos", (progress) => {
console.log(`上传进度: ${progress}%`);
});
```
### 组件使用
```tsx
<FormFileUpload
label="上传图片"
assetType="app-logos"
onUploadComplete={(assetIds) => {
console.log("上传完成:", assetIds);
}}
multiple
maxFiles={5}
/>
```
## 支持的文件类型
- 图片：JPEG, PNG, GIF, WebP, SVG
- 文档：PDF, TXT, DOC, DOCX
- 文件大小限制：10MB（可配置）
## 错误处理
- 文件类型验证
- 文件大小限制
- 网络错误处理
- 上传失败重试
- 用户友好的错误提示
## 性能优化
- 直接上传到OSS，减少服务器负载
- 进度跟踪提供良好的用户体验
- 支持多文件并发上传
- 文件预览和状态管理
## 测试
访问 `/test-upload` 页面可以测试所有上传功能，包括：
- 单文件上传
- 多文件上传
- 进度显示
- 错误处理
- 重试机制