wasabi完全兼容s3协议,直接使用aws sdk for php即可,只需配置正确endpoint(https://s3.wasabisys.com)、region(us-east-1)、密钥,并禁用use_path_style_endpoint;上传需显式设acl和contenttype,分页需手动处理nextcontinuationtoken,删除前确认版本控制已关闭。

Wasabi兼容S3协议,直接用AWS SDK for PHP就行
Wasabi不是独立生态,它完全兼容Amazon S3的REST API,所以不用找“Wasabi专用SDK”——Aws\S3\S3Client开箱即用,只要把endpoint和region配对即可。很多人卡在第一步,以为要装wasabi-sdk之类不存在的包,其实composer require aws/aws-sdk-php就够了。
- 必须指定
endpoint为https://s3.wasabisys.com(注意不是.com结尾的其他变体) -
region填us-east-1(Wasabi目前所有区域都映射到这个逻辑region,即使你选的是EU或JP节点) - Access Key和Secret Key从Wasabi控制台的「Access Keys」页面获取,不是AWS的密钥
- 禁用
use_path_style_endpoint(默认false),否则会拼出https://s3.wasabisys.com/bucket-name/...这种403错误路径
上传文件时注意Content-Type和ACL设置
PHP里用putObject()上传,默认ContentType是application/octet-stream,浏览器可能无法正确渲染图片、CSS等资源。另外Wasabi默认不公开对象,ACL: 'public-read'得显式声明,否则getObjectUrl()生成的链接会返回403。
- 图片上传建议加
'ContentType' => mime_content_type($file),避免用pathinfo($file, PATHINFO_EXTENSION)硬编码 - 如果用
UploadManager分段上传大文件,part_size建议设为5 * 1024 * 1024(5MB),太小会触发Wasabi的高频请求限流 - 不要依赖
getObjectUrl()生成预签名URL——Wasabi不支持S3的Signature Version 4临时凭证,只能设ACL公开后用固定域名访问
列出文件时分页参数容易漏掉ContinuationToken
Wasabi的ListObjectsV2响应里,当结果超过1000个,不会返回NextMarker,而是用NextContinuationToken。AWS SDK for PHP v3的listObjectsV2()方法默认只处理NextMarker,导致遍历中断。
- 手动检查响应里的
$result['NextContinuationToken'],下次请求传入'ContinuationToken' => $token - 别用
getIterator()自动翻页——它底层依赖NextMarker,对Wasabi无效 - 如果只是查少量文件,加
'MaxKeys' => 100并忽略翻页更稳妥
删除文件失败常见于权限或版本控制配置
Wasabi默认关闭版本控制(Versioning),但如果你在Bucket策略里启用了,deleteObject()只会插入一个删除标记(Delete Marker),文件实际还在。用户误以为删了,其实listObjectsV2()还能看到,只是GetObject返回404。
- 确认Bucket是否开启版本控制:登录Wasabi控制台 → Bucket → Properties → Versioning,关掉它再删
- 批量删除用
deleteObjects(),传'Delete' => ['Objects' => [['Key' => 'a.jpg'], ['Key' => 'b.png']],别用循环调deleteObject(),HTTP开销太大 - 遇到
AccessDenied错误,检查IAM策略是否包含s3:DeleteObject动作,且Resource匹配arn:aws:s3:::bucket-name/*
Wasabi的坑不在协议层面,而在细节适配:endpoint拼写、region语义、分页字段名、版本控制开关——这些地方错一个,错误信息往往很模糊,比如NotFound其实是认证失败,InvalidURI其实是use_path_style_endpoint开错了。动手前先用curl -v手动发个HEAD请求验证endpoint和auth头最省时间。
php免费学习视频:立即使用
踏上前端学习之旅,开启通往精通之路!从前端基础到项目实战,循序渐进,一步一个脚印,迈向巅峰!











