Spatie Laravel-Medialibrary 安装与配置完全指南

Spatie Laravel-Medialibrary 安装与配置完全指南

laravel-medialibrary Associate files with Eloquent models 项目地址: https://gitcode.com/gh_mirrors/la/laravel-medialibrary

前言

Spatie 的 Laravel-Medialibrary 是一个功能强大的媒体文件管理包，它可以帮助开发者轻松处理文件上传、转换和关联等操作。本文将详细介绍如何安装和配置这个包，让您能够快速上手使用。

环境准备

在开始安装之前，请确保您的项目满足以下要求：

• Laravel 8.0 或更高版本
• PHP 8.0 或更高版本
• Composer 已安装

安装步骤

1. 通过 Composer 安装基础包

运行以下命令安装基础包：

composer require "spatie/laravel-medialibrary"

如果您购买了专业版许可证，则需要安装专业版包：

composer require "spatie/laravel-media-library-pro"

2. 数据库准备

安装完成后，需要发布并运行迁移文件来创建媒体表：

php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"
php artisan migrate

3. 配置文件发布（可选）

虽然配置文件发布是可选的，但建议发布以便自定义配置：

php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-config"

配置详解

发布的配置文件位于 config/media-library.php，包含以下重要配置项：

基本配置

• disk_name: 指定存储媒体文件的磁盘，默认为 public
• max_file_size: 单个文件的最大大小限制（字节）
• media_model: 自定义媒体模型类
• image_driver: 图像处理引擎（gd 或 imagick）

队列配置

• queue_connection_name: 生成转换图像使用的队列连接
• queue_name: 使用的队列名称
• queue_conversions_by_default: 是否默认使用队列处理转换

图像优化配置

'image_optimizers' => [
    Spatie\ImageOptimizer\Optimizers\Jpegoptim::class => [
        '-m85', // 设置最大质量为85%
        '--strip-all', // 移除所有文本信息
        '--all-progressive', // 生成渐进式图像
    ],
    // 其他优化器配置...
]

响应式图像配置

'responsive_images' => [
    'width_calculator' => FileSizeOptimizedWidthCalculator::class,
    'use_tiny_placeholders' => true,
    'tiny_placeholder_generator' => Blurred::class,
]

专用媒体磁盘配置

建议为媒体文件配置专用磁盘，在 config/filesystems.php 中添加：

'media' => [
    'driver' => 'local',
    'root' => public_path('media'),
    'url' => env('APP_URL').'/media',
    'visibility' => 'public',
    'throw' => false,
]

然后在 .gitignore 中忽略媒体目录：

/media

优化工具安装

为了获得最佳性能，建议安装以下图像优化工具：

Ubuntu 系统

sudo apt install jpegoptim optipng pngquant gifsicle libavif-bin
npm install -g svgo

或使用 snap：

sudo apt install jpegoptim optipng pngquant gifsicle libavif-bin
sudo snap install svgo

MacOS 系统

brew install jpegoptim optipng pngquant svgo gifsicle libavif

专业版安装说明

专业版提供了更丰富的上传组件和功能，安装步骤如下：

1. 购买专业版许可证
2. 安装专业版包
3. 按照专业版文档完成配置

常见问题

1. 文件上传失败：检查磁盘配置和权限
2. 图像转换不工作：确认队列配置正确并运行
3. 优化效果不明显：检查优化工具是否安装正确

最佳实践

• 生产环境建议使用 S3 等远程存储
• 大型项目应配置专用队列处理媒体转换
• 定期清理临时文件和未使用的媒体

通过以上步骤，您已经成功安装并配置了 Laravel-Medialibrary，可以开始使用它强大的媒体管理功能了。

laravel-medialibrary Associate files with Eloquent models 项目地址: https://gitcode.com/gh_mirrors/la/laravel-medialibrary