如何解决Flysystem AWS S3 V3适配器private可见性配置不生效问题

问题表现 #

• 初始化AwsS3V3Adapter时向可见性转换器传入Visibility::PRIVATE参数，所有PutObject请求的ACL仍为public-read
• 对接Cloudflare R2存储时触发报错，因为R2不支持对象级public-read权限，所有对象上传请求必须使用privateACL
• 其余业务逻辑无异常，问题出在适配器初始化配置段

问题相关核心代码：

use League\Flysystem\AwsS3V3\AwsS3V3Adapter;
use League\Flysystem\AwsS3V3\PortableVisibilityConverter;
use League\Flysystem\FilesystemAdapter;
use League\Flysystem\Visibility;

class Fs
{
    protected function createAdapter(): FilesystemAdapter
    {
        return new AwsS3V3Adapter($client, $bucket, $subfolder, new PortableVisibilityConverter(Visibility::PRIVATE), null, [], false);
    }
}

问题根因 #

配置存在两处错误：

1. 可见性转换器参数传错：PortableVisibilityConverter构造函数的第一个入参是S3 public ACL对应的Flysystem可见性值，第二个入参才是S3 private ACL对应的Flysystem可见性值。你将Visibility::PRIVATE传入第一个参数，仅修改了ACL到Flysystem内部可见性的映射规则，没有修改适配器默认写入可见性——适配器默认写入仍使用public规则，所以请求里还是会带public-readACL，逻辑完全错位。
2. 未适配R2的权限模型：R2不支持对象级public-readACL，对象的公共访问完全由桶策略、R2托管公共域名配置控制，上传对象时携带public-readACL会直接触发参数错误，所有上传请求统一使用privateACL即可。

修复方案 #

方案1：保留动态切换公私可见性能力 #

如果后续需要手动控制部分文件的可见性，正确配置可见性转换器，同时在适配器默认请求参数中强制ACL为private适配R2：

protected function createAdapter(): FilesystemAdapter
{
    // 保持转换器默认映射规则即可：public对应public-read，private对应private
    $visibilityConverter = new PortableVisibilityConverter();
    return new AwsS3V3Adapter(
        $client,
        $bucket,
        $subfolder,
        $visibilityConverter,
        null,
        // 默认请求参数强制所有上传使用private ACL
        ['ACL' => Visibility::PRIVATE],
        false
    );
}

后续需要调整文件可见性时，在调用write/writeStream方法时传入visibility参数即可，注意R2场景下不需要传递public-readACL，公共访问能力通过桶层面配置实现即可。

方案2：全量私有场景最优配置 #

如果所有文件都不需要通过对象ACL控制访问权限（绝大多数R2使用场景都是如此），直接固定所有请求ACL为private即可，不需要额外调整转换器逻辑：

protected function createAdapter(): FilesystemAdapter
{
    return new AwsS3V3Adapter(
        $client,
        $bucket,
        $subfolder,
        new PortableVisibilityConverter(),
        null,
        ['ACL' => 'private'],
        false
    );
}

配置完成后抓包验证，PutObject请求的ACL头会固定为private，不会再出现public-read，可正常在R2环境运行。

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