Laravel使用自定义S3端点上传文件时返回false的问题排查

我在Laravel中已实现正常的AWS文件上传功能，上传代码及初始.env配置如下。开启S3存储桶的静态网站托管并配置CNAME（与桶名cdn.example.com一致）后，希望Storage::put()返回形如https://cdn.example.com/news/test.jpg的URL，而非默认的S3路径式URL。修改.env配置添加AWS_ENDPOINT并设置AWS_USE_PATH_STYLE_ENDPOINT=true后，Storage::put()返回false；将该配置改回false则上传恢复正常。请问该如何解决此问题？是否需要对存储桶进行额外设置？

上传代码 #

/**
 * Create image and save it to storage.
 *
 * @param  string $key
 * @param  string $relation
 * @return void
 */
public function createImage(string $key, $relation = 'image')
{
    if ($file = request()->file) {
        $image = Storage::put('/news', $file);

        $this->image()->create([
            'filename' => $image,
            'url' => Storage::url($image)
        ]);
    }
}

初始.env配置 #

AWS_ACCESS_KEY_ID=key
AWS_SECRET_ACCESS_KEY=secret
AWS_BUCKET=cdn.example.com
AWS_DEFAULT_REGION=ap-southeast-1
AWS_USE_PATH_STYLE_ENDPOINT=false

修改后的.env配置 #

AWS_ACCESS_KEY_ID=key
AWS_SECRET_ACCESS_KEY=secret
AWS_BUCKET=cdn.example.com
AWS_ENDPOINT=https://cdn.example.com
AWS_DEFAULT_REGION=ap-southeast-1
AWS_USE_PATH_STYLE_ENDPOINT=true

1. 修正.env配置逻辑 #

问题核心是AWS_ENDPOINT与AWS_USE_PATH_STYLE_ENDPOINT的搭配错误：

• AWS_ENDPOINT主要用于兼容非AWS的S3兼容存储（如MinIO），而你使用的是AWS原生S3的静态网站CNAME，应该用AWS_URL来指定自定义访问域名。
• 路径模式（AWS_USE_PATH_STYLE_ENDPOINT=true）会强制把桶名嵌入URL路径，与你的CNAME命名逻辑冲突，必须保持false以启用虚拟主机模式。

修正后的.env配置：

AWS_ACCESS_KEY_ID=key
AWS_SECRET_ACCESS_KEY=secret
AWS_BUCKET=cdn.example.com
AWS_DEFAULT_REGION=ap-southeast-1
AWS_USE_PATH_STYLE_ENDPOINT=false
AWS_URL=https://cdn.example.com

2. 配置文件系统URL生成规则 #

在config/filesystems.php的s3磁盘配置中显式指定url参数，确保Storage::url()生成自定义域名的URL：

'disks' => [
    // ...其他磁盘配置
    's3' => [
        'driver' => 's3',
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'region' => env('AWS_DEFAULT_REGION'),
        'bucket' => env('AWS_BUCKET'),
        'url' => env('AWS_URL'),
        'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', false),
    ],
],

3. 存储桶必备设置确认 #

确保S3存储桶完成以下配置：

• 开启静态网站托管，设置索引文档（如index.html），错误文档可按需配置。
• 配置桶策略允许公开读取静态资源（若需公开访问），示例策略：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::cdn.example.com/*"
        }
    ]
}

• 确认CNAME记录已正确指向S3静态网站终端节点（格式类似cdn.example.com.s3-website-ap-southeast-1.amazonaws.com），而非S3 API终端节点。

4. 验证配置生效 #

修改配置后执行php artisan config:clear清除缓存，重新测试：

• Storage::put()会正常返回文件相对路径（如news/test.jpg）。
• Storage::url($image)将生成https://cdn.example.com/news/test.jpg格式的目标URL。

内容的提问来源于stack exchange，提问作者Suhadak Akbar