结论是Laravel项目接入MinIO并非不能用，而是配错use_path_style_endpoint、endpoint尾部斜杠、废弃SDK包三处即触发403或400错误；正确配置后Storage::put()一行即可运行。
直接说结论：Laravel 项目换 MinIO，不是“能不能用”，而是“配错三处就 403 或 400”。只要 use_path_style_endpoint 开了、endpoint 不带尾部斜杠、不用废弃的 aws-sdk-php-laravel 包，Storage::put() 一行代码就能跑通。
为什么 Laravel 默认连不上 MinIO？
Laravel 的 Storage 门面走的是 Flysystem + AWS S3 驱动，但这个驱动默认按 AWS 官方 endpoint 行为签名——它假设你用的是 https://bucket.s3.region.amazonaws.com 这种虚拟主机式地址。MinIO 自建服务（尤其单机或内网部署）通常用 http://minio.example.com:9000 这种路径式地址，签名会失败，返回 403 Forbidden 或 InvalidAccessKeyId。
根本原因就一个：AWS SDK 默认关闭 use_path_style_endpoint，而 MinIO 要求必须开启。
-
use_path_style_endpoint => true必须显式写死在磁盘配置里，不能靠 env() 动态开关 -
endpoint值末尾绝对不能有/，比如http://127.0.0.1:9000✅，http://127.0.0.1:9000/❌ - 别碰
aws-sdk-php-laravel——它已废弃，且和 Laravel 11+ 的 Flysystem 3.x 冲突，装了反而覆盖掉正确驱动
composer require 和磁盘配置怎么写才不踩坑？
只装一个包：league/flysystem-aws-s3-v3，版本锁死 ^3.0（^2.0 不支持 MinIO v4 签名）。
在 config/filesystems.php 的 'disks' 数组里加：
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
'minio' => [
'driver' => 's3',
'key' => env('MINIO_ACCESS_KEY_ID'),
'secret' => env('MINIO_SECRET_ACCESS_KEY'),
'region' => env('MINIO_DEFAULT_REGION', 'us-east-1'),
'bucket' => env('MINIO_BUCKET'),
'endpoint' => env('MINIO_ENDPOINT'),
'use_path_style_endpoint' => true,
'options' => [
'scheme' => 'http', // MinIO 默认没开 TLS，别硬写 https
],
],
对应 .env：
FILESYSTEM_CLOUD=minio MINIO_ENDPOINT=http://127.0.0.1:9000 MINIO_ACCESS_KEY_ID=minio MINIO_SECRET_ACCESS_KEY=minio123 MINIO_BUCKET=uploads
-
region可填任意值（MinIO 不校验），但不能为空字符串，否则 Flysystem 报错 -
scheme设为http是为了绕过 TLS 验证失败；如果上了 HTTPS，再改回https并确保证书可信 - 测试时先用
php artisan tinker执行Storage::disk('minio')->put('test.txt', 'hello')，比写路由更快定位问题
上传文件时 ContentType 错乱怎么办？
Flysystem 默认调用 finfo_file() 推断 MIME 类型，但 MinIO 对 application/octet-stream 这类泛类型可能拒绝写入，或导致 CDN 缓存失效（比如图片被当成二进制流缓存）。
稳妥做法是手动指定 ContentType：
Storage::disk('minio')->put('avatar.jpg', $content, [
'ContentType' => 'image/jpeg',
]);
- 不要依赖扩展名自动推断，尤其处理用户上传的文件时
- 常见类型可查
mime_types.php映射表，或用mime_content_type($path)辅助判断 - 如果用
Storage::putFileAs()，它内部仍会推断 MIME，所以优先用原生put()+ 显式参数
真正卡住人的从来不是 MinIO 本身，而是 Laravel 配置里那几个看似无关紧要的布尔值和斜杠。把 use_path_style_endpoint 当成开关按钮，每次改完立刻 php artisan config:clear，不然缓存会骗你半天。
