文件上传功能

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

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

后端本地上传配置

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

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

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

// 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 属性来指定使用哪个存储磁盘和存储路径。所有上传组件都支持以下通用配置参数：

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

参数说明：

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

前端上传组件

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

图片上传组件 (UploadImage)

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

基础使用：

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

自定义存储配置：

<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)

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

基础使用：

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

自定义存储配置：

<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)

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

基础使用：

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

自定义存储配置：

<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 级别）设计的分片上传组件，支持断点续传和上传进度显示。适用于视频、大型文档等文件上传。

基础使用：

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

自定义分片配置：

<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	分片上传失败重试次数

配置示例：

<!-- 设置分片大小为 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)

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

基础使用（单文件）：

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

多文件上传：

<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 等）。

基础使用：

<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 等）。

基础使用：

<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）