直接用 composer require 安装阿里云 OSS PHP SDK 即可，需注意 PHP 与 SDK 版本兼容性：PHP 7.2–7.4 用 ^2.7，PHP 8.0+ 用 ^3.0；初始化 OssClient 必须显式传入 endpoint、AccessKey ID 和 Secret，endpoint 为纯域名格式；常见错误包括 endpoint 拼错、AccessKey 权限不足、Bucket 不存在、SSL 证书失效。
直接用 composer require 安装阿里云 OSS PHP SDK 即可，不需要手动下载或改 autoload。但要注意 SDK 版本、PHP 版本兼容性，以及常见因配置缺失导致的 InvalidAccessKeyId 或 cURL error 60 类错误。
确认 PHP 版本与 SDK 版本匹配
阿里云官方 SDK aliyun/oss-sdk-php v2.x（如 2.7.0）要求 PHP >= 7.2；v3.x（如 3.0.0+）要求 PHP >= 8.0。如果你用的是 PHP 7.4，别盲目装最新版，否则 composer install 会失败或运行时报 ParseError。
- 查当前 PHP 版本：
php -v - PHP 7.2–7.4：执行
composer require aliyun/oss-sdk-php:^2.7
- PHP 8.0+：执行
composer require aliyun/oss-sdk-php:^3.0
- 不加版本号默认装最新版，可能踩坑
安装后需手动配置 Endpoint、AccessKey 和 Bucket
SDK 不会自动读取环境变量或配置文件，OssClient 实例化时必须显式传入 $endpoint、$accessKeyId、$accessKeySecret。很多人漏写 $endpoint 或用了错误格式（比如带 http:// 或少了 -internal 内网地址后缀），导致连接超时或签名失败。
- Endpoint 必须是纯域名，例如：
https://oss-cn-hangzhou.aliyuncs.com（外网）或https://oss-cn-hangzhou-internal.aliyuncs.com（同地域 ECS 内网） - AccessKey ID 和 Secret 应从阿里云 RAM 控制台获取，**不要硬编码在代码里**，推荐从
$_ENV或.env文件加载 - 示例初始化：
$ossClient = new \OSS\OssClient($accessKeyId, $accessKeySecret, $endpoint);
常见报错与绕过 SSL 验证的临时方案
本地开发时容易遇到 cURL error 60: SSL certificate problem，尤其 Windows 或旧版 cURL 环境。这不是 SDK 问题，而是 CA 证书路径未配置。生产环境严禁关闭 SSL 验证，但开发调试可临时设置：
立即学习“PHP免费学习笔记（深入）”；
- 在实例化前加：
OSS\OssClient::setDebugMode(true); // 可选，看详细请求
- 临时禁用 SSL 验证（仅限开发）：
$ossClient = new \OSS\OssClient($accessKeyId, $accessKeySecret, $endpoint, null, null, ['ssl' => ['verify' => false]]);
- 更稳妥的做法是下载最新 CA 包（如 cacert.pem），然后在
php.ini中设置：curl.cainfo = "/path/to/cacert.pem"
Endpoint 拼错、AccessKey 权限不足、Bucket 不存在、SSL 证书失效——这四类问题占了 90% 的初始化失败。检查时优先确认这四个点，比翻 SDK 文档更快。
