PHP 8.5 配置 MinIO 上传需用 aws/aws-sdk-php v3.x，核心是正确设置 endpoint（如 http://localhost:9000）、region（如 us-east-1）、credentials，并启用 use_path_style_endpoint=true；上传中文文件名须 UTF-8 编码后 rawurlencode，bucket 需显式创建且命名合规。
PHP 8.5 配置 MinIO 上传文件，核心是用官方推荐的 aws/aws-sdk-php（v3.x）或轻量替代方案 minio/minio-php。前者兼容性更广、维护活跃；后者专为 MinIO 优化，体积小、API 更直白。下面以主流且稳妥的 aws/aws-sdk-php 为例，分步说明关键配置和实操要点。
安装 SDK 并确认 PHP 环境兼容性
MinIO 官方 PHP SDK 要求 PHP ≥ 7.4，而 aws/aws-sdk-php v3.290+ 已完全支持 PHP 8.5。推荐使用 Composer 安装：
- 运行
composer require aws/aws-sdk-php - 确保已启用
curl和json扩展（PHP 8.5 默认开启） - 若用 S3 兼容模式，无需额外开启
openssl（除非启用 HTTPS 或签名验证）
初始化 MinIO 客户端：endpoint、region、凭证三要素
MinIO 不强制 region，但 AWS SDK 要求传入非空值（可填 us-east-1）。endpoint 必须是完整 URL，不含路径，不带尾部斜杠：
- ✅ 正确：
http://localhost:9000、http://192.168.1.10:9000 - ❌ 错误：
localhost:9000（缺协议）、http://localhost:9000/（尾部斜杠）、http://localhost:9000/minio（含路径） - 凭证默认为
minioadmin/minioadmin，生产环境务必改用环境变量或配置中心管理
示例初始化代码：
立即学习“PHP免费学习笔记（深入）”；
$s3Client = new S3Client([
'version' => 'latest',
'region' => 'us-east-1',
'endpoint'=> 'http://localhost:9000',
'credentials' => [
'key' => $_ENV['MINIO_ACCESS_KEY'] ?? 'minioadmin',
'secret' => $_ENV['MINIO_SECRET_KEY'] ?? 'minioadmin',
],
'use_path_style_endpoint' => true, // ⚠️ MinIO 8.0+ 默认关闭 path-style，此行仅在旧版或特殊网关场景需要
]);
创建 Bucket 并上传文件（含中文名处理）
MinIO 不自动创建 bucket，必须显式调用 createBucket。对象 key（即文件路径）若含中文，必须由客户端 UTF-8 编码 + URL 编码，否则预签名 URL 下载会失败：
- 先检查 bucket 是否存在：
$s3Client->doesBucketExist('my-bucket') - 若不存在，执行
$s3Client->createBucket(['Bucket' => 'my-bucket']) - 上传中文文件名时，对 key 做
rawurlencode(mb_convert_encoding($filename, 'UTF-8'))，例如用户协议.pdf→%E7%94%A8%E6%88%B7%E5%8D%8F%E8%AE%AE.pdf - 上传方式推荐
putObject（小文件）或upload（大文件自动分片）
示例上传：
$key = rawurlencode(mb_convert_encoding('用户头像.jpg', 'UTF-8'));
$s3Client->putObject([
'Bucket' => 'my-bucket',
'Key' => $key,
'Body' => fopen('/tmp/avatar.jpg', 'rb'),
'ACL' => 'public-read',
]);
常见报错与快速排查
Connection refused？大概率 MinIO 服务未启动，或监听地址未绑定到外部 IP（默认只监听 localhost:9000）—— 启动时加 --address :9000 即可。
-
InvalidEndpointException：检查 endpoint 格式是否合规（协议+域名/IP+端口，无路径无空格） -
SignatureDoesNotMatch：key 未编码，或系统时间与服务端偏差超 15 分钟（需校准 NTP） - 上传后 listObjectsV2 返回空？确认 bucket 名全小写、无下划线、长度 3–63 字符（S3 兼容规范）
