---
url: /docs/5.0/server/upload.md
---
# 文件上传功能

CatchAdmin  提供了完整的文件上传解决方案，支持本地上传、OSS 云存储、COS 云存储等多种上传方式。系统基于 Laravel Filesystem 构建，为开发者提供了灵活且强大的文件管理能力。

本文档将详细介绍各种上传组件的使用方法，包括图片上传、单文件上传、多文件上传、大文件分片上传等功能。除特殊说明外，所有组件默认基于本地存储。

## 后端本地上传配置

CatchAdmin  基于 Laravel Filesystem 提供了两个预配置的本地存储磁盘（disk），满足不同的文件存储需求：

* **uploads**: 用于存储用户上传的文件，支持公开访问，适合图片、文档等需要直接访问的文件
* **static**: 用于存储系统内部文件，私有访问，适合配置文件、日志等敏感文件

以下是系统内置的磁盘配置，开发者可以根据项目需求添加自定义的 disk 配置：

```php
// config/filesystem.php
[
    'disks' => [
        // 公共上传目录 - 用户上传的文件存储
        'uploads' => [
            'driver' => 'local',                    // 使用本地存储驱动
            'root' => storage_path('uploads'),      // 存储根目录：storage/uploads
            'url' => env('APP_URL').'/uploads',     // 公开访问URL前缀
            'visibility' => 'public',               // 文件可公开访问
            'throw' => false,                       // 操作失败时不抛出异常
        ],

        // 私有静态文件目录 - 系统内部文件存储
        'static' => [
            'driver' => 'local',                    // 使用本地存储驱动
            'root' => storage_path('static'),       // 存储根目录：storage/static
            'visibility' => 'private',              // 文件私有访问
            'directory_visibility' => 'private',    // 目录私有访问
            'throw' => false,                       // 操作失败时不抛出异常
        ],
    ]
]
```

### 磁盘配置参数说明

| 参数                   | 说明              | uploads 配置                  | static 配置                   |
| ---------------------- | ----------------- | ----------------------------- | ----------------------------- |
| `driver`               | 存储驱动类型      | local（本地存储）             | local（本地存储）             |
| `root`                 | 文件存储根目录    | storage/uploads               | storage/static                |
| `url`                  | 公开访问 URL 前缀 | /uploads                      | 无（私有访问）                |
| `visibility`           | 文件访问权限      | public（公开）                | private（私有）               |
| `directory_visibility` | 目录访问权限      | 继承文件权限                  | private（私有）               |
| `throw`                | 错误处理方式      | false（返回错误而不抛出异常） | false（返回错误而不抛出异常） |

### 前端组件配置参数

前端上传组件通过 `props` 属性来指定使用哪个存储磁盘和存储路径。所有上传组件都支持以下通用配置参数：

```ts
{
  // 指定存储磁盘，对应后端 filesystem 配置中的 disk 名称
  disk: {
    type: String,
    default: 'uploads'    // 默认使用 uploads 磁盘（公开访问）
  },
  // 指定存储子目录，相对于磁盘根目录的路径
  path: {
    type: String,
    default: 'attachments'  // 默认存储在 attachments 文件夹下
  }
}
```

**参数说明：**

* `disk`: 选择后端配置的存储磁盘，如 `uploads`（公开）或 `static`（私有）
* `path`: 文件存储的子目录，最终存储路径为 `{disk.root}/{path}/filename`

## 前端上传组件

CatchAdmin  提供了多种上传组件，满足不同的业务场景需求。

### 图片上传组件 (UploadImage)

用于上传单张图片文件，支持图片预览和格式限制。

**基础使用：**

```vue
<UploadImage v-model="formData.logo" class="w-20 h-20" :file-extensions="['.png', '.jpg', '.jpeg']" />
```

**自定义存储配置：**

```vue
<UploadImage v-model="formData.logo" class="w-20 h-20" :file-extensions="['.png', '.jpg', '.jpeg']" disk="uploads" path="avatars" />
```

**组件属性：**

| 属性              | 类型   | 默认值                     | 说明                       |
| ----------------- | ------ | -------------------------- | -------------------------- |
| `v-model`         | String | -                          | 绑定上传后的文件路径       |
| `class`           | String | -                          | CSS 样式类名，设置组件尺寸 |
| `file-extensions` | Array  | `['.jpg', '.png', '.gif']` | 允许上传的文件扩展名       |
| `disk`            | String | `'uploads'`                | 存储磁盘名称               |
| `path`            | String | `'images'`                 | 存储子目录路径             |
| `max-size`        | Number | `2048`                     | 最大文件大小（KB）         |

### 单文件上传组件 (UploadFile)

用于上传单个文件，支持多种文件格式，适合文档、表格等文件上传。

**基础使用：**

```vue
<UploadFile v-model="files" :file-extensions="['.md', '.txt', '.csv', '.xlsx']" />
```

**自定义存储配置：**

```vue
<UploadFile v-model="files" :file-extensions="['.md', '.txt', '.csv', '.xlsx']" disk="uploads" path="documents" />
```

**组件属性：**

| 属性              | 类型          | 默认值                     | 说明                           |
| ----------------- | ------------- | -------------------------- | ------------------------------ |
| `v-model`         | String/Object | -                          | 绑定上传后的文件信息           |
| `file-extensions` | Array         | `['.txt', '.doc', '.pdf']` | 允许上传的文件扩展名           |
| `disk`            | String        | `'uploads'`                | 存储磁盘名称                   |
| `path`            | String        | `'files'`                  | 存储子目录路径                 |
| `max-size`        | Number        | `10240`                    | 最大文件大小（KB）             |
| `accept`          | String        | -                          | HTML accept 属性，文件类型限制 |

### 多文件上传组件 (UploadFiles)

用于同时上传多个文件，支持批量文件处理，适合需要上传多个文档的场景。

**基础使用：**

```vue
<UploadFiles v-model="files" :file-extensions="['.md', '.txt', '.csv', '.xlsx']" />
```

**自定义存储配置：**

```vue
<UploadFiles v-model="files" :file-extensions="['.md', '.txt', '.csv', '.xlsx']" disk="uploads" path="batch-files" :max-files="10" />
```

**组件属性：**

| 属性              | 类型    | 默认值                     | 说明                   |
| ----------------- | ------- | -------------------------- | ---------------------- |
| `v-model`         | Array   | `[]`                       | 绑定上传后的文件列表   |
| `file-extensions` | Array   | `['.txt', '.doc', '.pdf']` | 允许上传的文件扩展名   |
| `disk`            | String  | `'uploads'`                | 存储磁盘名称           |
| `path`            | String  | `'files'`                  | 存储子目录路径         |
| `max-files`       | Number  | `5`                        | 最大上传文件数量       |
| `max-size`        | Number  | `10240`                    | 单个文件最大大小（KB） |
| `multiple`        | Boolean | `true`                     | 是否支持多选文件       |

### 大文件分片上传组件 (ChunkUpload)

专为大文件（GB 级别）设计的分片上传组件，支持断点续传和上传进度显示。适用于视频、大型文档等文件上传。

**基础使用：**

```vue
<ChunkUpload v-model="basic.video" action="/upload/chunk" />
```

**自定义分片配置：**

```vue
<ChunkUpload v-model="basic.video" action="/upload/chunk" :chunk-size="5 * 1024 * 1024" :max-file-size="5 * 1024 * 1024 * 1024" />
```

**组件属性：**

| 属性            | 类型          | 默认值                   | 说明                           |
| --------------- | ------------- | ------------------------ | ------------------------------ |
| `v-model`       | String/Object | -                        | 绑定上传后的文件信息           |
| `action`        | String        | `'/upload/chunk'`        | 分片上传接口地址               |
| `chunk-size`    | Number        | `2 * 1024 * 1024`        | 分片大小（字节），默认 2MB     |
| `max-file-size` | Number        | `2 * 1024 * 1024 * 1024` | 最大文件大小（字节），默认 2GB |
| `auto-upload`   | Boolean       | `true`                   | 是否自动开始上传               |
| `retry-count`   | Number        | `3`                      | 分片上传失败重试次数           |

**配置示例：**

```vue
<!-- 设置分片大小为 3MB -->
<ChunkUpload v-model="basic.video" action="/upload/chunk" :chunk-size="3 * 1024 * 1024" />

<!-- 设置最大文件限制为 5GB -->
<ChunkUpload v-model="basic.video" action="/upload/chunk" :max-file-size="5 * 1024 * 1024 * 1024" />
```

### 附件上传组件 (AttachUpload)

通用附件上传组件，支持各种文件类型的上传，可配置单文件或多文件模式。

**基础使用（单文件）：**

```vue
<AttachUpload v-model="formData.attachment" class="w-20 h-20" />
```

**多文件上传：**

```vue
<AttachUpload v-model="formData.attachments" class="w-20 h-20" :multi="true" />
```

**组件属性：**

| 属性        | 类型         | 默认值          | 说明                                     |
| ----------- | ------------ | --------------- | ---------------------------------------- |
| `v-model`   | String/Array | -               | 单文件模式绑定字符串，多文件模式绑定数组 |
| `class`     | String       | -               | CSS 样式类名                             |
| `multi`     | Boolean      | `false`         | 是否支持多文件上传                       |
| `disk`      | String       | `'uploads'`     | 存储磁盘名称                             |
| `path`      | String       | `'attachments'` | 存储子目录路径                           |
| `max-files` | Number       | `5`             | 多文件模式下最大文件数量                 |
| `max-size`  | Number       | `10240`         | 最大文件大小（KB）                       |

## 云存储上传

CatchAdmin  支持主流云存储服务，提供更高的可靠性和 CDN 加速能力。

### 阿里云 OSS 上传组件 (OssUpload)

集成阿里云对象存储服务，支持直传和服务端签名上传，提供高可用的文件存储方案。

**前提条件：** 需要在后台管理系统中配置 OSS 相关参数（AccessKey、SecretKey、Bucket 等）。

![ 上传-OSS上传](https://image.catchadmin.com/202505120832848.png)

**基础使用：**

```vue
<OssUpload v-model="formData.logo" class="w-20 h-20" />
```

**组件属性：**

| 属性       | 类型   | 默认值      | 说明                 |
| ---------- | ------ | ----------- | -------------------- |
| `v-model`  | String | -           | 绑定上传后的文件 URL |
| `class`    | String | -           | CSS 样式类名         |
| `path`     | String | `'uploads'` | OSS 存储路径前缀     |
| `max-size` | Number | `10240`     | 最大文件大小（KB）   |

### 腾讯云 COS 上传组件 (CosUpload)

集成腾讯云对象存储服务，提供稳定的云端文件存储和访问能力。

**前提条件：** 需要在后台管理系统中配置 COS 相关参数（SecretId、SecretKey、Bucket、Region 等）。

![ 上传-cos上传](https://image.catchadmin.com/202505120832297.png)

**基础使用：**

```vue
<CosUpload v-model="formData.logo" class="w-20 h-20" />
```

**组件属性：**

| 属性       | 类型   | 默认值      | 说明                 |
| ---------- | ------ | ----------- | -------------------- |
| `v-model`  | String | -           | 绑定上传后的文件 URL |
| `class`    | String | -           | CSS 样式类名         |
| `path`     | String | `'uploads'` | COS 存储路径前缀     |
| `max-size` | Number | `10240`     | 最大文件大小（KB）   |