应执行 composer require cloudinary/cloudinary_php 安装官方 SDK，确认 PHP ≥ 7.4 并启用 curl、json 扩展，配置 cloud_name 等参数后调用 upload 时需指定 secure => true 获取 HTTPS URL。
直接执行 composer require cloudinary/cloudinary_php 就行
这是官方维护的 PHP SDK，不是第三方“PHP-Cloudinary”库——后者在 Packagist 上并不存在，搜不到、装不上，强行用会报 Package cloudinary/php-cloudinary not found 错误。别被非官方命名误导，认准 cloudinary/cloudinary_php 这个包名。
安装前必须确认 PHP 版本和扩展支持
该 SDK 要求 PHP ≥ 7.4，且必须启用 curl 和 json 扩展。如果你用的是 PHP 8.2+，还要注意：SDK v2.x 支持到 PHP 8.2，但尚未完全适配 8.3 的新类型系统（比如 mixed 类型提示冲突可能触发警告）。运行前先检查：
php -v<br>php -m | grep -E '^(curl|json)$'
若缺失扩展，Ubuntu/Debian 下执行 sudo apt install php-curl php-json；macOS + Homebrew + PHP 8.2 可用 brew install php@8.2-curl 补齐。
初始化时别漏掉 Cloudinary::config() 或环境变量
装完不配置就调用 Uploader::upload() 会直接抛出 CloudinaryException: Missing cloud_name。两种配置方式任选其一：
立即学习“PHP免费学习笔记（深入）”；
- 代码内硬编码（仅开发测试）：
Cloudinary::config(['cloud_name' => 'your_cloud_name', 'api_key' => 'xxx', 'api_secret' => 'yyy']); - 更安全的做法：把三个参数写进
.env文件，再用dotenv加载，或直接设为系统环境变量：CLOUDINARY_CLOUD_NAME=xxx CLOUDINARY_API_KEY=yyy CLOUDINARY_API_SECRET=zzz php your_script.php
注意：API Secret 绝对不能暴露在前端或 Git 历史里，哪怕只是 demo 项目也建议用环境变量隔离。
上传后返回的 URL 默认是 HTTP，需要显式加 secure => true
直接调 Uploader::upload('local.jpg') 返回的 secure_url 字段才是 HTTPS 链接；如果只取 url 字段，生产环境可能被浏览器拦截混合内容。常见写法：
$result = Uploader::upload('photo.jpg', ['secure' => true]);<br>// 此时 $result['url'] 已是 https://...<br>// 不要依赖 $result['secure_url'] 再做二次判断
另外，带签名的 URL（如生成带有效期的临时链接）必须传 sign_url => true，否则 generateSignedUrl() 方法不可用。
Cloudinary 的 CDN 分发逻辑藏在 URL path 里，改参数不会触发重传，但改 transformation 会实时生成新图——这点容易误以为要反复上传，其实不用。
