# big-file-upload

**Repository Path**: ai-project_7/big-file-upload

## Basic Information

- **Project Name**: big-file-upload
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-10
- **Last Updated**: 2025-12-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# 大文件分片上传网站

一个基于 koa 的大文件上传网站。

# 技术依赖
- nuxt3
- typescript
- pinia
- unocss
- pnpm
- node:20.19.0
- koa

# 功能特性
前端选择大文件上传（分片上传策略、可以暂停、断点续传），node后端接收文件并把大文件上传到upload文件夹

# 快速开始

## 环境要求
- Node.js: 20.19.0
- pnpm: >=8.0.0

## 安装依赖
```bash
pnpm install
```

## 启动开发服务器

### 启动前端（Nuxt 3）
```bash
pnpm dev
```
前端服务运行在: http://localhost:3000

### 启动后端（Koa）
```bash
pnpm server:dev
```
后端服务运行在: http://localhost:3001

## 构建生产版本
```bash
pnpm build
pnpm preview
```

## 项目结构
```
cursor-demo/
├── assets/              # 静态资源
│   └── css/             # 样式文件
├── components/          # Vue 组件
│   └── FileUploader.vue # 文件上传组件
├── composables/         # 组合式函数
│   └── useChunkedUpload.ts # 分片上传逻辑
├── pages/               # 页面路由
│   └── index.vue        # 首页
├── server/              # Koa 后端服务器
│   ├── index.js        # 服务器入口
│   └── uploads/        # 上传文件存储目录
└── upload/             # 最终文件存储目录
```

## API 接口

### POST /api/upload/check
检查已上传的分片（支持断点续传）
```json
{
  "fileId": "string",
  "fileName": "string",
  "fileSize": "number",
  "totalChunks": "number"
}
```

### POST /api/upload/chunk
上传单个分片
- Content-Type: multipart/form-data
- 参数: file, fileId, chunkIndex, fileName, totalChunks

### POST /api/upload/merge
合并所有分片为完整文件
```json
{
  "fileId": "string",
  "fileName": "string",
  "totalChunks": "number"
}
```

# 规范

### 1. Props 规范

// ✅ 推荐：使用 TypeScript interface
interface Props {
  // 必需属性
  title: string
  count: number
  
  // 可选属性
  description?: string
  
  // 联合类型
  size?: 'small' | 'medium' | 'large'
  
  // 对象类型
  user?: {
    id: number
    name: string
  }
  
  // 数组类型
  items?: Array<{ id: number; text: string }>
}

// 使用默认值
const props = withDefaults(defineProps<Props>(), {
  description: '',
  size: 'medium',
  items: () => []
})

### 2. 组件命名

// ✅ 多单词组件名（避免与 HTML 元素冲突）
components/UserProfile.vue
components/ImageUploader.vue
components/PaymentDialog.vue

// ❌ 避免单个单词
components/User.vue
components/Image.vue
components/Dialog.vue

// ✅ 组件文件使用 PascalCase
components/ai-video/TemplateCard.vue

// ❌ 避免 kebab-case 文件名
components/ai-video/template-card.vue

### 3. UnoCSS 优先

<template>
  <!-- ✅ 优先使用 UnoCSS 原子类 -->
  <div class="flex items-center justify-between px-4 py-2 bg-blue-500 text-white">
    内容
  </div>
  
  <!-- ✅ 复杂样式使用 scoped CSS -->
  <div class="custom-component">
    特殊样式
  </div>
</template>

<style scoped>
.custom-component {
  background: linear-gradient(to right, #667eea 0%, #764ba2 100%);
  border-radius: 8px;
}
</style>

---

### 4. 响应式设计

<template>
  <!-- ✅ 使用 UnoCSS 响应式前缀 -->
  <div class="px-4 sm:px-6 md:px-8 lg:px-12">
    <!-- 移动端 16px, 小屏 24px, 中屏 32px, 大屏 48px -->
  </div>
  
  <!-- ✅ 使用响应式类 -->
  <div class="flex-col sm:flex-row">
    <!-- 移动端垂直，桌面端水平 -->
  </div>
</template>


### 5. 文件命名

# ✅ 组件文件 - PascalCase
components/UserProfile.vue
components/ImageUploader.vue
components/PaymentDialog.vue

# ✅ Composables - camelCase
composables/useImageUpload.ts
composables/useFacebookPixel.ts

# ✅ Utils - camelCase
utils/formatDate.ts
utils/validateEmail.ts

# ✅ Stores - camelCase
stores/globalStore.ts
stores/paymentStore.ts

# ✅ 类型定义 - PascalCase 或 camelCase
types/User.ts
types/api.d.ts

## 注释规范

### 1. 文件头注释

/**
 * @file 用户资料组件
 * @description 显示和编辑用户个人信息
 * @author Your Name
 * @date 2025-10-17
 */

### 2. 函数注释
/**
 * 格式化日期为指定格式
 * @param date - 要格式化的日期
 * @param format - 日期格式，默认 'YYYY-MM-DD'
 * @returns 格式化后的日期字符串
 * @example
 * formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
 * // => '2025-10-17 14:30:00'
 */
const formatDate = (date: Date, format = 'YYYY-MM-DD'): string => {
  // 实现...
}

### 3. 复杂逻辑注释

// ✅ 为复杂逻辑添加注释
const processImage = async (file: File) => {
  // 1. 验证文件格式和大小
  if (!validateFile(file)) {
    throw new Error('Invalid file')
  }
  
  // 2. 压缩图片（如果超过 2MB）
  const compressedFile = file.size > 2 * 1024 * 1024
    ? await compressImage(file)
    : file
  
  // 3. 上传到服务器
  const uploadResult = await uploadFile(compressedFile)
  
  // 4. 返回处理结果
  return uploadResult
}

// ❌ 避免显而易见的注释
const count = 0  // 定义 count 变量

---