ThinkPHP下载云存储文件需先拉取到本地临时目录再响应下载，不可直接传云URL；须校验权限、净化文件名、加随机前缀命名、下载后及时清理临时文件，或采用直链跳转方案。
ThinkPHP 从云存储（如阿里 OSS、腾讯 COS、七牛）下载文件并同步到本地，本质不是“同步”，而是“拉取+落地”。云存储本身不提供节点间自动同步机制，所谓“同步本地”，是指在当前服务器上生成一份可直接读取的副本。关键在于：不绕过本地临时存储，又避免大文件堆积和安全风险。
必须先拉取到本地临时目录
ThinkPHP 的 response()->download() 只接受服务器上的真实绝对路径，不能传云存储 URL（如 https://xxx.oss-cn-shanghai.aliyuncs.com/a.pdf）。否则会报错或返回空响应。
- 用官方 SDK（如
aliyuncs/oss-sdk-php）调用$ossClient->getObject()，流式写入本地临时路径（如runtime/downloads/） - 确保目录可写、有执行权限，且不在 Web 可访问路径下（防止被直接访问）
- 写入后校验文件大小是否为 0，避免空文件触发下载失败
下载前做权限与安全校验
用户请求下载某个云上文件，不代表他有权下载——需业务层拦截验证。
- 查数据库确认该文件记录归属当前登录用户（例如
file_records.user_id = $this->auth->id） - 对原始文件名净化：
basename($inputName)剥离路径，再白名单校验后缀（如只允许['pdf', 'xlsx', 'jpg']） - 临时文件命名建议加随机前缀 + 时间戳（如
dl_5f8a2b1c_report_202610151450.pdf），防覆盖和猜测
下载完成及时清理临时文件
临时文件不清理会导致磁盘占满，尤其高频下载场景。
立即学习“PHP免费学习笔记（深入）”；
- 下载响应发出后立即
unlink($localPath)（注意：必须在response()->download()调用之后，且未 exit） - 更稳妥做法是异步清理：把临时路径写入队列或缓存（如 Redis），由定时任务每 5 分钟扫描并删除 10 分钟前的文件
- 若使用
Filesystem::disk('oss')->readStream()流式处理，可边读边写边删，内存友好但逻辑稍复杂
替代方案：直链跳转（免本地落地）
如果业务允许用户直接访问云存储 URL（比如 Bucket 设置为 public-read），就不需要同步本地。
- 前端直接跳转
Filesystem::disk('oss')->url($path)生成的地址（自动带签名或拼公网域名） - 优点：零磁盘占用、无 IO 延迟；缺点：无法统一控制下载行为（如限速、审计、断点续传）
- 适合公开资源或 CDN 加速场景，不适合需鉴权、审计、定制响应头的业务文件
