阿里云 OSS PHP SDK 已停更，应使用 alibabacloud/sdk 替代；旧包 aliyun-oss-php-sdk 自 2018 年归档，仅支持 PHP 5.4–5.6，不兼容 Composer 2.x 及新版 PHP；新版需通过 composer require alibabacloud/sdk 安装，客户端为 AlibabaCloud\Oss\OssClient，须传入 access_key_id、access_key_secret、endpoint 等参数，且 region 必须与 endpoint 匹配。
阿里云 OSS PHP SDK 已不再维护 aliyun-oss-php-sdk 这个旧包，直接 composer require aliyun-oss-php-sdk 会失败或引入过时、不兼容的版本 —— 这是当前最常踩的坑。
为什么 composer require aliyun-oss-php-sdk 不工作
该包早在 2018 年就已归档（Archived），最后更新为 v2.3.0，仅支持 PHP 5.4–5.6，且不兼容 Composer 2.x 的依赖解析规则。执行后通常报错：
Could not find package aliyun-oss-php-sdk at any version
或提示 Package aliyun-oss-php-sdk has a PHP requirement incompatible with your PHP version。
阿里云官方早已迁移至新版统一 SDK：alibabacloud/sdk，OSS 功能作为其中的 AlibabaCloud\Oss 服务模块提供。
立即学习“PHP免费学习笔记（深入）”；
正确安装方式：用 alibabacloud/sdk + oss 服务包
新版 SDK 支持 PHP 7.2+（推荐 8.0+），自动管理凭证、签名、重试、日志等，且与阿里云其他服务（如 STS、RAM、VOD）共用同一套客户端体系。
运行以下命令：
composer require alibabacloud/sdk
然后在代码中按需加载 OSS 模块（无需额外 require 子包，SDK 会按需加载）：
- 确保
autoload已生效（即已运行composer install或composer dump-autoload） - OSS 客户端类为
AlibabaCloud\Oss\OssClient，不是旧版的OssClient - 必须显式启用
oss服务：调用AlibabaCloud::api('oss')或直接 newOssClient
初始化 OSS 客户端的最小可用示例
注意：新版 SDK 要求使用 AccessKeyId / AccessKeySecret + Endpoint，不接受旧版的 Bucket 参数直接传入构造函数。
$client = new \AlibabaCloud\Oss\OssClient([
'region' => 'oss-cn-hangzhou',
'access_key_id' => 'your-access-key-id',
'access_key_secret' => 'your-access-key-secret',
'endpoint' => 'https://oss-cn-hangzhou.aliyuncs.com',
]);
关键点：
-
region必须与endpoint匹配（例如oss-cn-shanghai对应https://oss-cn-shanghai.aliyuncs.com） - 不要拼写成
accessKeyId（驼峰）—— 正确是access_key_id（下划线） - 如果使用临时 Token（STS），需额外传入
security_token字段
常见报错与绕过方案
遇到 Class 'AlibabaCloud\Oss\OssClient' not found？检查：
- 是否漏了
use AlibabaCloud\Oss\OssClient;（命名空间必须显式 use） - 是否误用了旧版文档里的
new OssClient(...)（没加完整命名空间） - 是否在非 Composer 环境下手动复制了 vendor 文件（不推荐，自动加载会失效）
- PHP 版本低于 7.2 —— 新版 SDK 强制要求
ext-json和ext-curl，且不兼容php:5.6镜像
如果你的项目强依赖旧版行为（比如已有大量 OssClient::putObject 调用），建议封装一层适配器，而不是降级回存档包 —— 后者无 HTTPS 证书校验修复、无 HTTP/2 支持、无活跃维护。
