Laravel 配置阿里云 OSS 磁盘时，driver 必须为 'oss'，root 是 Bucket 内子路径；endpoint 需匹配地域与网络类型，url 必须显式配置为 OSS 访问域名，否则 url() 返回错误链接。
配置 Laravel 的 filesystems.php 磁盘时，driver 和 root 别写反
阿里云 OSS 不是传统文件系统，Laravel 默认的 local 或 s3 驱动不能直接复用；必须用 oss 驱动（依赖 aliyuncs/oss-sdk-php），且 root 参数实际是 OSS 的 bucket 下的子路径（不是本地目录），容易误填成服务器路径。
实操建议：
Laravel Cloud
下载
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- 确认已安装 SDK：
composer require aliyuncs/oss-sdk-php - 在
config/filesystems.php中新增磁盘，driver必须为'oss'，不是's3'或'custom' -
root填的是 OSS Bucket 内的前缀路径（如'images/'），留空表示根目录；填错会导致文件上传到意料之外的位置 - 必填项：
access_key_id、access_key_secret、bucket、endpoint（注意选内网 or 公网，跨地域会 403）
Endpoint 选错导致 cURL error 6: Could not resolve host 或 403 Forbidden
OSS 的 endpoint 不是随便填的域名 —— 它和 Bucket 所在地域强绑定，且分公网、内网、VPC 三种类型。ECS 上用公网 endpoint 会绕行、慢；用错地域或协议（http/https）也会失败。
实操建议：
- 查 Bucket 地域：进阿里云 OSS 控制台 → 进 Bucket → 看「概览」页右上角「地域」，例如
oss-cn-hangzhou - 对应 endpoint 示例：
https://oss-cn-hangzhou.aliyuncs.com（公网 HTTPS）、http://oss-cn-hangzhou-internal.aliyuncs.com（同地域 ECS 内网） - 不要手敲 endpoint，从控制台「Bucket 域名」区域直接复制「外网访问域名」或「内网访问域名」
- 如果用
http协议但 Laravel 配置了https强制跳转，可能触发 301 后失败，统一用https更稳妥
上传文件时 put() 返回 false 或抛出 ClientException
常见于权限、路径或 ACL 设置不当。OSS 默认不继承 Bucket 权限，且 put() 的第二个参数（内容）如果是本地路径，Laravel 不会自动读取文件内容 —— 它会把路径字符串当二进制传上去。
实操建议：
- 上传文件内容必须是字符串或 resource：
Storage::disk('oss')->put('a.jpg', file_get_contents($path))，而不是put('a.jpg', $path) - 确保 RAM 子账号有
oss:PutObject权限，且 Policy 中Resource匹配你的bucket和prefix - 如果需要公开可读，设置
ACL：在 disk 配置里加'options' => ['acl' => 'public-read']，否则默认私有，url()生成的是临时签名链接 - 注意
url()行为：私有 bucket 下调用它会返回带 Signature 的临时链接（有效期默认 3600 秒），不是永久 URL
Laravel 的 Storage::url() 在 OSS 磁盘下不返回预期域名
这是因为 url() 默认拼接的是 APP_URL + 路径，对 OSS 完全无效。必须显式配置 url 键，指向 OSS 的访问域名（即 Bucket 绑定的自定义域名或 OSS 域名）。
实操建议：
- 在
config/filesystems.php对应磁盘中加：'url' => 'https://your-bucket.oss-cn-hangzhou.aliyuncs.com' - 如果用了 CDN 或自定义域名（如
https://static.example.com），就填那个；别留空，也别指望 Laravel 自动推导 - 该
url只影响url()方法，不影响put()、get()等操作的实际 endpoint - 测试时直接
dd(Storage::disk('oss')->url('test.jpg'))，看输出是否为你期望的完整可访问链接
