Webman中OSS上传常失败或返回504，根本原因是官方PHP SDK的putObject为同步阻塞式，不支持协程、分片与重试，在Swoole环境下易阻塞Worker并触发Nginx/ALB 60秒超时；须改用uploadFile（自动分片上传）并配置partSize、maxRetries及合法ContentType等元数据。
Webman 项目直接用 OSS SDK 上传大文件（尤其是视频）容易卡死或超时，根本原因是默认的 putObject 是同步阻塞式上传，且未启用分片和重试机制。 必须改用 uploadFile 或手动分片 + initMultipartUpload 才能稳定处理 10MB 以上的文件。
为什么 Webman 的 OSS 上传常失败或返回 504
Webman 默认运行在 Swoole 上，而阿里云官方 PHP SDK（aliyun-oss-php-sdk）v2.x 的 putObject 方法底层依赖 cURL 同步请求，在协程环境下会阻塞整个 Worker 进程；上传视频这类大文件时，若网络抖动或 OSS 响应慢，极易触发 Nginx 或 ALB 的 60 秒超时，返回 504 Gateway Timeout。
- 现象：上传 20MB 视频时，前端长时间无响应，日志里出现
cURL error 28: Operation timed out或 Swoole 报Connection reset by peer - 根本原因：SDK 未适配协程，
putObject不支持断点续传，也不自动分片 - 兼容方案：必须切换到
uploadFile—— 它内部自动调用分片上传接口，支持进度回调、失败重试、临时磁盘缓存 - 注意：
uploadFile要求本地临时路径可写（如/tmp），且 PHP 进程有读取该文件的权限
Webman 中配置 OSS 客户端的正确姿势
不要在每次请求中 new 一个 OssClient，也不要在 config/autoload/oss.php 里硬编码密钥。应该利用 Webman 的容器绑定 + 环境变量驱动：
Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。
- 把
AccessKeyId、AccessKeySecret、Endpoint、Bucket全部设为环境变量，例如ALIYUN_OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com - 在
app/bootstrap.php中绑定单例：$container->bind('OssClient', function ($container) { return new \Aliyun\OSS\OssClient( $_ENV['ALIYUN_OSS_ACCESS_KEY_ID'] ?? '', $_ENV['ALIYUN_OSS_ACCESS_KEY_SECRET'] ?? '', $_ENV['ALIYUN_OSS_ENDPOINT'] ?? '' ); }); - 上传时显式指定
options：['partSize' => 5 * 1024 * 1024, 'maxRetries' => 3]，避免小分片拖慢速度，也防止弱网下反复失败 - 禁用 SDK 自动检测 endpoint：确保
Endpoint值带协议（https://），否则可能因 DNS 解析失败导致连接异常
上传视频前必须校验的三件事
用户上传 MP4 文件不等于就能直接扔进 OSS —— 阿里云对 object 的 key（即文件名）、Content-Type、元数据都有隐性约束，漏掉任意一项都可能导致 CDN 回源失败或浏览器无法播放：
- key 必须是合法路径格式，不能含
../、空字符或控制符；建议用md5(uniqid()).'.mp4'生成，再拼上目录前缀如video/ - 必须显式设置
ContentType：MP4 对应video/mp4，AVI 是video/x-msvideo，否则 OSS 默认存为application/octet-stream，CDN 或浏览器可能拒绝解析 - 关键元数据要补全：
['Expires' => '+1 year', 'Cache-Control' => 'public, max-age=31536000']，否则 CDN 节点不会缓存，每次请求都回源，流量翻倍 - 额外提醒：如果用自定义域名访问视频，需确认该域名已备案、已绑定 Bucket、且 CNAME 解析生效（通常需 10–30 分钟）
OSS 回源到 CDN 时常见的 403 和 404
把视频传到 OSS 后，用 CDN 域名访问却返回 403 Forbidden 或 404 Not Found，90% 是权限与路由错配：
- 403：Bucket 权限不是
public-read，或开启了“阻止公共访问”（新版控制台默认开启，必须手动关闭） - 404：CDN 源站填的是内网 endpoint（如
oss-cn-hangzhou-internal.aliyuncs.com）—— CDN 节点无法访问阿里云内网，必须填外网域名（xxx.oss-cn-hangzhou.aliyuncs.com） - CDN 缓存规则没配：默认只缓存图片类后缀，需手动添加
.mp4、.mov到“缓存策略”的扩展名列表中 - 测试技巧：直接用
curl -I https://your-cdn-domain.com/test.mp4看X-Cache头，如果是HIT说明缓存生效，MISS或EXPIRED就要查源站连通性和缓存规则
真正麻烦的不是上传本身，而是上传之后的链路完整性：从 OSS 权限、CDN 源站配置、缓存规则、自定义域名解析，到前端 video 标签的 preload 和 controls 属性是否合理 —— 任一环断裂，用户看到的就是黑屏或无限 loading。动手前先用最小化 MP4 文件走通整条链路，比堆代码更省时间。
