Laravel项目如何接入阿里云OSS云存储？（图文教程）

必须安装 overtrue/flysystem-oss 才能使 storage::disk(‘oss’) 正常工作，仅装 aliyuncs/oss-sdk-php 不够；需正确配置 endpoint（带 https://）、bucket（纯名称）、access_key、secret_key，并运行 php artisan config:clear。

composer require 阿里云 OSS SDK 后为什么 Storage::disk('oss') 报错？

laravel 默认不认阿里云 OSS，装了 aliyuncs/oss-sdk-php 只是加了底层 SDK，没注册 Laravel 的 Flysystem 适配器。必须额外装 overtrue/flysystem-oss，它才是让 Storage::disk('oss') 能跑起来的桥梁。

• 不装 overtrue/flysystem-oss，只装 aliyuncs/oss-sdk-php，调用 Storage::disk('oss')->put(...) 会直接抛 InvalidArgumentException: Disk [oss] does not exist
• 安装命令是 composer require "overtrue/flysystem-oss:^4.0"（Laravel 9/10 推荐用 v4；v3 对 PHP 8.1+ 有兼容问题）
• 装完别忘了运行 php artisan config:clear，否则新配置可能不生效

config/filesystems.php 里 oss 磁盘配置哪些字段不能写错？

阿里云 OSS 的 endpoint、bucket、access_key 和 secret_key 四个字段必须严格对应控制台值，尤其 endpoint 容易漏掉协议或写成内网地址。

• endpoint 必须带 https://，例如 <a href="https://www.php.cn/link/116c87e094144d0002cff857e56a322f">https://www.php.cn/link/116c87e094144d0002cff857e56a322f</a>；写成 oss-cn-hangzhou.aliyuncs.com 或 http://... 会导致 curl 错误
• bucket 是纯桶名，不要加 .oss-cn-hangzhou.aliyuncs.com 后缀，否则上传路径会变成双重域名
• access_key 和 secret_key 建议从 RAM 子账号获取，主账号密钥泄露风险高
• 如果用自定义域名（如 <a href="https://www.php.cn/link/ca904c1dfe5c1e4415ce964959278c45">https://www.php.cn/link/ca904c1dfe5c1e4415ce964959278c45</a>），要关掉 isCName 的自动判断，显式设为 true，并确保 DNS 已解析且 OSS 绑定了该域名

上传文件时 Storage::disk('oss')->put() 返回 false 但没报错？

Flysystem 默认静默失败，put() 返回 false 多半是权限或网络问题，不是代码逻辑错误。

• 检查 OSS 控制台：Bucket 是否开启「公共读」？如果没开，又没配签名 URL，前端直传会 403
• 查看 Laravel 日志里的实际异常，常藏在 storage/logs/laravel.log 中，关键词是 OSSException 或 cURL Error
• 上传大文件（>100MB）建议改用 putFileAs() + 分片上传中间件，原生 put() 容易超时或内存溢出
• 本地开发时若用 Homestead/Valet，确认系统时间是否和 NTP 同步，时间偏差 >15 分钟会导致签名失效，报 The difference between the request time and the current time is too large

生成可公开访问的 URL 为什么总是 404？

Storage::disk('oss')->url() 默认返回的是私有签名 URL（含 Expires 和 Signature 参数），不是永久链接。要公开 URL，得关签名或换方式。

• Bucket 权限设为「公共读」后，直接拼接 <a href="https://www.php.cn/link/a34335a3bede0f17a7af733b697ad848">https://www.php.cn/link/a34335a3bede0f17a7af733b697ad848</a>; 最稳，比如 <a href="https://www.php.cn/link/7a4127a65ee360ef0110b01a23ab04a3">https://www.php.cn/link/7a4127a65ee360ef0110b01a23ab04a3</a>
• 若坚持用 url()，需在磁盘配置里加 'options' => ['isPrivate' => false]，否则它默认走私有签名逻辑
• 注意路径分隔符：OSS 用正斜杠 /，windows 开发环境用 storage_path() 读本地文件时路径可能是反斜杠，上传前记得用 str_replace('', '/', $path) 统一

阿里云 OSS 的坑不在代码多难写，而在配置项之间互相咬合——endpoint 写错一个字符、bucket 多写个点、时间不同步几分钟，都会让整个流程卡在“看起来没问题，但就是不动”。上线前最好用真实 bucket 跑一遍完整读写链路，别只测 put() 成功就收工。