媒体库

媒体库是 CarefreeCMS 的文件管理中心，用于统一管理网站的所有图片、视频、文档等媒体文件。

媒体库概述

功能特点

统一管理

集中存储所有媒体文件
分类组织，便于查找
支持多种文件类型
可视化管理界面

高效上传

支持拖拽上传
批量上传文件
实时上传进度
自动生成缩略图

智能处理

自动压缩图片
生成多种尺寸
提取文件信息
病毒扫描（可选）

便捷使用

快速搜索文件
预览文件
复制文件链接
在编辑器中插入

访问媒体库

入口位置

方式一：独立访问

左侧菜单 → 内容管理 → 媒体库

方式二：编辑器调用

文章编辑 → 点击"插入图片" → 媒体库弹窗

方式三：字段选择

文章封面 → 点击"选择图片" → 媒体库弹窗

界面布局

┌─────────────────────────────────────────┐
│  媒体库                    [上传] [新建]  │
├──────┬──────────────────────────────────┤
│ 全部 │  [缩略图模式] [列表模式]         │
│ 图片 │  ┌────┐ ┌────┐ ┌────┐ ┌────┐   │
│ 视频 │  │图片│ │图片│ │图片│ │图片│   │
│ 文档 │  └────┘ └────┘ └────┘ └────┘   │
│ 音频 │  ┌────┐ ┌────┐ ┌────┐ ┌────┐   │
│ 其他 │  │图片│ │图片│ │图片│ │图片│   │
│      │  └────┘ └────┘ └────┘ └────┘   │
├──────┴──────────────────────────────────┤
│  已选: 0 个文件        共 256 个文件     │
└─────────────────────────────────────────┘

上传文件

上传方式

方式一：点击上传

点击上传按钮
选择文件
确认上传

方式二：拖拽上传

打开文件管理器
拖拽文件到媒体库区域
自动开始上传

方式三：批量上传

按住 Ctrl/Cmd 选择多个文件
或选择整个文件夹
一次性上传

支持的文件类型

图片文件

格式：JPG、JPEG、PNG、GIF、WebP、SVG、BMP、ICO
大小：最大 10MB
用途：文章配图、封面、Logo、图标

视频文件

格式：MP4、AVI、MOV、WMV、FLV、MKV
大小：最大 100MB
用途：视频教程、产品展示、宣传片

音频文件

格式：MP3、WAV、OGG、AAC、FLAC
大小：最大 50MB
用途：背景音乐、播客、音频教程

文档文件

格式：PDF、DOC、DOCX、XLS、XLSX、PPT、PPTX、TXT
大小：最大 20MB
用途：附件下载、资料分享

压缩文件

格式：ZIP、RAR、7Z、TAR、GZ
大小：最大 50MB
用途：批量文件下载

上传限制

文件大小

// config/upload.php
return [
    'image' => [
        'max_size' => 10 * 1024 * 1024,  // 10MB
        'exts' => ['jpg', 'jpeg', 'png', 'gif', 'webp'],
    ],
    'video' => [
        'max_size' => 100 * 1024 * 1024, // 100MB
        'exts' => ['mp4', 'avi', 'mov'],
    ],
    'document' => [
        'max_size' => 20 * 1024 * 1024,  // 20MB
        'exts' => ['pdf', 'doc', 'docx', 'xls', 'xlsx'],
    ],
];

数量限制

单次上传：最多 50 个文件
并发上传：3 个文件同时上传
总存储空间：根据服务器配置

上传进度

上传时显示实时进度：

┌─────────────────────────────────┐
│ 正在上传文件...                 │
│                                 │
│ image1.jpg     ████████░░ 80%  │
│ image2.jpg     ███░░░░░░░ 30%  │
│ image3.jpg     排队中...        │
│                                 │
│ [取消上传]                      │
└─────────────────────────────────┘

文件管理

查看文件

缩略图模式

图片显示缩略图
文件显示图标
文件名显示在下方
适合图片浏览

列表模式

文件名          类型    大小     上传时间
image1.jpg     图片    256KB    2024-01-15
document.pdf   文档    1.2MB    2024-01-14
video.mp4      视频    15MB     2024-01-13

详细信息

文件名：banner.jpg
文件类型：image/jpeg
文件大小：512 KB
图片尺寸：1920 x 1080 像素
上传时间：2024-01-15 14:30:25
上传者：admin
URL 地址：https://example.com/uploads/2024/01/15/banner.jpg
使用次数：5

文件搜索

按名称搜索

搜索框输入：banner
结果：显示所有包含"banner"的文件

按类型筛选

全部文件 | 图片 | 视频 | 文档 | 音频 | 其他

按时间筛选

今天 | 最近7天 | 最近30天 | 自定义时间范围

高级搜索

文件名：banner
文件类型：图片
大小范围：100KB - 1MB
上传时间：2024-01-01 至 2024-01-31
上传者：admin

文件操作

预览

点击文件查看大图
支持图片、视频、PDF 预览
键盘左右键切换文件

编辑信息

文件名：可修改
描述：添加文件说明
标签：添加分类标签

复制链接

URL：https://example.com/uploads/2024/01/15/banner.jpg
Markdown：![](https://example.com/uploads/2024/01/15/banner.jpg)
HTML：<img src="https://example.com/uploads/2024/01/15/banner.jpg">

下载文件

点击下载按钮
保存到本地

删除文件

选择文件
点击删除按钮
确认删除
文件移入回收站

批量操作

勾选多个文件 → 批量下载
勾选多个文件 → 批量删除
勾选多个文件 → 移动到分组

文件分组

创建分组

点击 新建分组 按钮
输入分组名称
选择父分组（可选）
保存

分组示例

媒体库
├── 文章配图
│   ├── 技术文章
│   ├── 生活随笔
│   └── 摄影作品
├── 封面图片
├── 产品图片
│   ├── 产品A
│   └── 产品B
└── 视频资源

管理分组

重命名分组

右键点击分组
选择"重命名"
输入新名称
保存

移动分组

拖拽分组到新位置
或编辑分组选择新的父分组

删除分组

右键点击分组
选择"删除"
选择文件处理方式：
- 移动到其他分组
- 或一并删除

文件分组

上传时分组

选择目标分组
上传文件
文件自动归入该分组

移动到分组

选择文件
右键或点击"移动"
选择目标分组
确认移动

批量分组

勾选多个文件
批量操作 → 移动到分组
选择分组
确认

图片处理

自动处理

上传时处理

// 自动处理配置
'image_process' => [
    'auto_resize' => true,        // 自动调整大小
    'max_width' => 1920,          // 最大宽度
    'max_height' => 1080,         // 最大高度
    'quality' => 85,              // 压缩质量
    'strip_metadata' => true,     // 移除元数据
]

生成缩略图

'thumbnails' => [
    'small' => ['width' => 150, 'height' => 150],
    'medium' => ['width' => 400, 'height' => 300],
    'large' => ['width' => 800, 'height' => 600],
]

存储路径

uploads/2024/01/15/
├── banner.jpg              # 原图
├── banner_small.jpg        # 小图
├── banner_medium.jpg       # 中图
└── banner_large.jpg        # 大图

手动编辑

在线编辑器

功能：
- 裁剪
- 旋转
- 翻转
- 调整亮度/对比度
- 滤镜效果
- 添加文字/水印

操作步骤

选择图片
点击"编辑"按钮
使用编辑工具
预览效果
保存（另存为新文件或覆盖）

水印设置

配置水印

// config/watermark.php
return [
    'enable' => true,
    'type' => 'image',           // image 或 text
    'image' => '/images/watermark.png',
    'text' => 'CarefreeCMS',
    'position' => 'bottom-right', // 位置
    'offset_x' => 10,            // X 偏移
    'offset_y' => 10,            // Y 偏移
    'opacity' => 50,             // 透明度
];

自动添加

上传时自动添加水印
仅对指定类型图片添加
可设置最小尺寸要求

在编辑器中使用

插入图片

TinyMCE 编辑器

光标定位到插入位置
点击"插入图片"按钮
媒体库弹窗打开
选择图片
设置图片属性
确认插入

图片属性

图片 URL：自动填充
替代文字：SEO 优化（必填）
图片标题：鼠标悬停显示
尺寸：宽度 x 高度
对齐方式：左对齐/居中/右对齐

插入视频

方式一：上传视频

点击"插入视频"
从媒体库选择
设置播放器参数
插入

方式二：嵌入外部视频

<!-- YouTube -->
<iframe src="https://www.youtube.com/embed/VIDEO_ID"></iframe>

<!-- Bilibili -->
<iframe src="//player.bilibili.com/player.html?bvid=BV_ID"></iframe>

插入文件

下载链接

<a href="/uploads/2024/01/document.pdf" download>
  点击下载文档
</a>

按钮样式

<a href="/uploads/2024/01/document.pdf" class="btn btn-primary" download>
  <i class="fa fa-download"></i> 下载 PDF
</a>

存储管理

存储位置

本地存储

目录：backend/public/uploads/
结构：/uploads/年/月/日/文件名
示例：/uploads/2024/01/15/banner_abc123.jpg

云存储

支持：
- 阿里云 OSS
- 腾讯云 COS
- 七牛云
- 又拍云
- AWS S3

配置云存储

阿里云 OSS

// config/storage.php
return [
    'type' => 'oss',
    'access_key_id' => 'YOUR_ACCESS_KEY',
    'access_key_secret' => 'YOUR_SECRET_KEY',
    'bucket' => 'your-bucket',
    'endpoint' => 'oss-cn-beijing.aliyuncs.com',
    'domain' => 'https://cdn.example.com',
];

腾讯云 COS

return [
    'type' => 'cos',
    'secret_id' => 'YOUR_SECRET_ID',
    'secret_key' => 'YOUR_SECRET_KEY',
    'bucket' => 'your-bucket',
    'region' => 'ap-beijing',
    'domain' => 'https://cdn.example.com',
];

存储空间

查看使用情况

总空间：100 GB
已使用：45.6 GB (45.6%)
剩余：54.4 GB

文件统计：
图片：12,345 个 (30.2 GB)
视频：156 个 (12.8 GB)
文档：892 个 (2.6 GB)

清理空间

1. 删除未使用文件
2. 压缩大图片
3. 清空回收站
4. 删除重复文件

API 接口

上传文件

请求

POST /api/media/upload
Content-Type: multipart/form-data
Authorization: Bearer {token}

--boundary
Content-Disposition: form-data; name="file"; filename="image.jpg"
Content-Type: image/jpeg

[binary data]
--boundary--

响应

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "id": 1,
    "filename": "image.jpg",
    "url": "https://example.com/uploads/2024/01/15/image_abc123.jpg",
    "size": 102400,
    "mime_type": "image/jpeg",
    "width": 1920,
    "height": 1080
  }
}

获取文件列表

请求

GET /api/media?type=image&page=1&page_size=20

响应

{
  "code": 200,
  "data": {
    "list": [
      {
        "id": 1,
        "filename": "banner.jpg",
        "url": "https://example.com/uploads/2024/01/15/banner.jpg",
        "size": 512000,
        "create_time": "2024-01-15 14:30:25"
      }
    ],
    "total": 256
  }
}

删除文件

请求

DELETE /api/media/1
Authorization: Bearer {token}

响应

{
  "code": 200,
  "message": "删除成功"
}

最佳实践

文件命名

规范命名

✓ 好的命名：
banner-home-2024.jpg
product-smartphone-front.jpg
avatar-user-123.png

✗ 差的命名：
IMG_001.jpg
图片1.jpg
asjdhkasd.jpg

使用英文

避免中文文件名
使用小写字母
用连字符分隔
体现文件用途

组织管理

分组规划

按用途分组：
- 文章配图
- 产品图片
- Banner 广告
- 用户头像

按时间分组：
- 2024年
- 2023年

按项目分组：
- 项目A
- 项目B

定期清理

每月检查未使用文件
删除重复文件
压缩大图片
清空回收站

性能优化

图片优化

1. 使用合适格式
   - 照片：JPG
   - 图标/Logo：PNG/SVG
   - 动图：GIF/WebP

2. 控制文件大小
   - 宽度不超过 1920px
   - 质量 85% 足够
   - 启用懒加载

3. 响应式图片
   - 准备多种尺寸
   - 根据屏幕加载

CDN 加速

1. 配置云存储
2. 绑定 CDN 域名
3. 开启 HTTPS
4. 设置缓存策略

安全设置

文件类型限制

仅允许安全文件类型
禁止可执行文件
检查文件真实类型

文件大小限制

根据实际需求设置
防止恶意上传
保护服务器资源

访问权限

上传需要登录
设置用户配额
记录操作日志

常见问题

上传失败怎么办？

检查项目

文件是否超过大小限制
文件类型是否允许
网络连接是否正常
服务器空间是否充足

解决方法

减小文件大小
转换文件格式
重新上传
联系管理员

如何批量下载文件？

勾选多个文件
点击"批量下载"
系统打包为 ZIP
下载压缩包

删除的文件能恢复吗？

回收站恢复

进入回收站
找到被删除文件
点击"恢复"
文件恢复到原位置

注意

回收站文件保留 30 天
超期自动永久删除
永久删除无法恢复

如何更换云存储？

配置新的云存储
测试上传功能
迁移现有文件
切换存储方式
验证文件访问