火山引擎PHP SDK安装需满足PHP≥7.4且guzzlehttp/guzzle≥7.0，VodClient初始化须显式配置region、endpoint及校时，uploadMedia需设timeout≥300并用绝对路径，CDN刷新为异步任务且URL须带协议，异常需解析getResponseBody定位。
火山引擎 SDK 安装失败或 composer require 报错
直接用官方包 volcengine/volc-sdk-php 是唯一推荐路径，但很多人卡在 composer 源或 PHP 版本上。SDK 要求 PHP >= 7.4，且依赖 guzzlehttp/guzzle >= 7.0 —— 如果项目里已有旧版 Guzzle（比如 6.x），composer require 会冲突报错，不是 SDK 本身有问题。
- 先运行
composer show guzzlehttp/guzzle看当前版本，若低于 7.0，得先升级或协调兼容 - 国内建议换源：
composer config -g repo.packagist composer https://packagist.phpcomposer.com（或阿里云镜像） - 安装命令必须带版本约束避免自动拉取不兼容快照：
composer require volcengine/volc-sdk-php:^1.0 - 别手动下载 ZIP 或拷文件——SDK 内部有 autoloader 和 signature 签名逻辑，缺一不可
VodClient 初始化后调用 getPlayInfo 返回签名错误
火山点播服务（VOD）的几乎所有接口都强制要求鉴权，而错误常出在 Credentials 构造环节。不是 AK/SK 写错了，而是时区、时间戳、Region 配置不匹配导致签名算错。
-
region必须显式传，比如cn-north-1，不能留空或填default - 服务器系统时间偏差超过 5 分钟就会被拒绝，用
ntpdate -q time.windows.com校时 - 初始化时别漏掉
endpoint：VOD 的 endpoint 是https://vod.cn-north-1.volces.com，不是通用域名 - 示例关键片段：
$client = new VodClient([ 'credentials' => new Credentials('your_ak', 'your_sk'), 'region' => 'cn-north-1', 'endpoint' => 'https://vod.cn-north-1.volces.com' ]);
上传文件到 VodClient::uploadMedia 卡住或超时
火山 VOD 的上传不是直传 OSS，而是走服务端中转 + 分片上传流程。uploadMedia 实际做了三件事：预签名 → 分片上传 → 提交转码。任意一环网络或配置不对都会卡在“上传中”状态，且默认超时只有 30 秒。
- 务必设置长超时：
'timeout' => 300加到 client 配置里，尤其上传大视频时 - 本地文件路径必须是绝对路径，相对路径（如
./video.mp4）会静默失败 - 上传前检查文件 MIME 类型是否被 VOD 支持，
mp4、mov可以，webm默认不支持，需提工单开通 - 不要自己拼 URL 去 POST，SDK 已封装完整流程；自行实现容易漏掉
X-Dateheader 或分片 checksum 校验
CDN 刷新缓存用 CdnClient::submitRefreshTask 不生效
CDN 刷新接口返回成功（HTTP 200 + task_id），不代表资源已刷新。常见误解是“提交即刷新”，实际是异步任务，且有配额、URL 格式、协议等硬限制。
立即学习“PHP免费学习笔记（深入）”；
- URL 必须带协议和完整域名，
https://example.com/a.jpg✅，/a.jpg❌，example.com/a.jpg❌ - 单次最多提交 100 条 URL，超限会截断，不报错也不提示
- 免费额度每天 1000 次，超额后任务进队列但状态一直是
pending，查describeRefreshTasks才能确认 - 刷新的是 CDN 节点缓存，源站内容没更新的话，刷新完还是旧内容——先确认源站已更新再刷
VolcEngineException，但 message 里混着 HTTP 状态码和业务 code，得自己 parse $e->getResponseBody() 才能定位真问题。别只看 echo $e->getMessage()。 
