Laravel 11中S3文件下载时如何正确设置文件名？

我在Laravel 11中使用S3存储桶，控制器里写了如下函数，用于让Chrome浏览器下载指定文件：

public function downloadFile(Materials $material) 
{
    Gate::authorize('view', $material);
    $fileInfo = pathinfo($material->filename);
    $filename = urlencode($material->name) . "." . $fileInfo['extension'];
    return Storage::disk('s3')->response( $material->filename, $filename );
}

问题是下载后的文件名不是设置的$filename，而是S3的哈希值。但响应头看起来是正常的：

Content-Disposition:
inline; filename="DatenschutzerklC3A4rung+Muster.docx"; filename*=utf-8''Datenschutzerkl%25C3%25A4rung%2BMuster.docx

我还尝试了以下两种方式，都没效果：

// 方式1
return Storage::disk('s3')->response(
    $material->filename,
    urldecode($filename),
    ['Content-Disposition' => 'attachment']
);

// 方式2
return Storage::disk('s3')->response(
    $material->filename,
    $filename,
    ['Content-Disposition' => "attachment; filename=\"$filename\"; filename*=UTF-8''$filename"]
);

请问我哪里出错了？

问题原因及解决办法 #

1. 重复编码导致解析失败
   响应头里的filename*字段出现%25C3%25A4，这是双重URL编码的结果——原本的ä被编码成%C3%A4后，又被再次编码成%25C3%25A4，Chrome无法正确识别这种重复编码的文件名。Laravel的response()方法会自动对文件名做URL编码，你手动提前调用urlencode()完全多余，反而引发问题。

2. 正确的写法
   去掉手动编码步骤，直接传入原始文件名，让Laravel处理编码逻辑，同时明确设置Content-Disposition为attachment确保触发下载行为：

public function downloadFile(Materials $material) 
{
    Gate::authorize('view', $material);
    $fileInfo = pathinfo($material->filename);
    // 直接使用原始名称，无需手动编码
    $filename = $material->name . "." . $fileInfo['extension'];
    
    return Storage::disk('s3')->response(
        $material->filename,
        $filename,
        ['Content-Disposition' => 'attachment']
    );
}

3. 手动控制Content-Disposition的写法
   如果需要自定义filename*字段格式，确保只做一次编码，推荐用rawurlencode()（符合RFC标准，空格转%20而非+）：

public function downloadFile(Materials $material) 
{
    Gate::authorize('view', $material);
    $fileInfo = pathinfo($material->filename);
    $filename = $material->name . "." . $fileInfo['extension'];
    $encodedFilename = rawurlencode($filename);
    
    return Storage::disk('s3')->response(
        $material->filename,
        $filename,
        [
            'Content-Disposition' => "attachment; filename=\"$filename\"; filename*=UTF-8''$encodedFilename"
        ]
    );
}

关键注意点 #

• 不要提前对文件名做URL编码，Laravel的S3响应方法会自动处理。
• 务必设置Content-Disposition: attachment，避免Chrome以预览模式打开文件（部分文件类型会直接在浏览器显示而非触发下载）。
• 优先用rawurlencode()处理特殊字符，比urlencode()更适配文件名场景。

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