Laravel默认不直接支持MinIO，因其Storage门面依赖Flysystem，而官方S3驱动仅适配AWS签名逻辑与endpoint行为；MinIO虽兼容S3 API，但需显式配置use_path_style_endpoint => true、正确设置endpoint（无尾部斜杠）、并避免使用已废弃的aws-sdk-php-laravel包。
为什么 Laravel 默认不直接支持 MinIO
Laravel 的 Storage 门面底层依赖 Flysystem，而官方 s3 驱动默认只适配 AWS S3 的签名逻辑和 endpoint 行为。MinIO 虽然兼容 S3 API，但关键差异在于：AWS_USE_PATH_STYLE_ENDPOINT 必须设为 true（尤其在 MinIO 早期版本或自建部署时），否则会因签名失败返回 403 Forbidden 或 InvalidAccessKeyId；另外，AWS_ENDPOINT 必须显式指定，且不能带 trailing slash。
用 Flysystem + aws-s3-v3 驱动对接 MinIO 的实操要点
别装 aws-sdk-php-laravel——它已废弃，且与 Laravel 9+ 的 Flysystem 3.x 不兼容。正确路径是：
- 执行
composer require league/flysystem-aws-s3-v3 "^3.0"（注意版本号，^2.0不支持 MinIO 的 v4 签名） - 在
config/filesystems.php中添加磁盘配置，**必须显式传入use_path_style_endpoint => true**：
'minio' => [
'driver' => 's3',
'key' => env('AWS_ACCESS_KEY_ID'),
'secret' => env('AWS_SECRET_ACCESS_KEY'),
'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
'bucket' => env('AWS_BUCKET'),
'endpoint' => env('AWS_ENDPOINT'),
'use_path_style_endpoint' => true,
'options' => [
'scheme' => 'http', // MinIO 默认无 TLS，别写 https
],
],
常见错误现象：Client error: `PUT http://minio.example.com/bucket/key` resulted in a `400 Bad Request` response，基本就是 use_path_style_endpoint 没开或 endpoint 多了个 /。
上传文件时绕过 Flysystem 自动 MIME 推断陷阱
Flysystem 会尝试用 finfo_file() 推断 MIME 类型并作为 ContentType 传给 MinIO，但 MinIO 对某些类型（如 application/octet-stream）可能拒绝写入或导致 CDN 缓存失效。更稳妥的做法是手动指定：
- 上传时用
Storage::disk('minio')->put($path, $content, ['ContentType' => $mimeType]) - 若传
UploadedFile实例，先取原始 MIME：$file->getClientMimeType()，别用$file->getMimeType()（后者可能被本地扩展名干扰） - 对图片类文件，强制设为
image/webp或image/jpeg，避免 MinIO 返回Content-Type: binary/octet-stream
删除文件前务必确认路径格式是否匹配 MinIO 的 Key 规范
MinIO 的 object key 是纯字符串路径，不区分“目录”，所以 Storage::disk('minio')->delete('images/avatar.jpg') 可行，但以下情况会失败：
- 路径开头带
/（如/images/avatar.jpg）→ MinIO 认为 key 是空字符串 + 前缀，查不到 - 路径含 Windows 风格反斜杠
\→ 直接 400 - URL 解析后提取的 key 错误：比如从
https://cdn.example.com/bucket/images/a.jpg中用parse_url()+path得到/bucket/images/a.jpg，实际应截掉 bucket 名和域名前缀，只留images/a.jpg
最稳的方式是：统一用 basename(parse_url($url, PHP_URL_PATH)) 提取文件名，再结合业务规则拼出 key；或者干脆在数据库里存原始 key，而非完整 URL。
MinIO 的兼容性边界比 AWS S3 更窄，尤其在签名、重定向、预签名 URL 有效期等细节上。别假设「S3 能跑，MinIO 就一定行」——每个 putObject 或 deleteObject 调用背后，都得盯着实际 HTTP 请求头和响应体看。
