AWS PHP StreamWrapper文件函数在EC2实例中无法正常工作的问题

这种跨PHP版本、跨环境的S3流包装器问题我碰到过好几次，既然本地PHP 5.6能正常工作，说明代码逻辑没问题，问题大概率出在EC2的PHP 7.2环境配置、权限或者依赖差异上，咱们一步步来捋：

1. AWS SDK版本兼容性问题 #

PHP 7.2相对于5.6在流处理上有不少细节调整，旧版本的AWS SDK for PHP（比如v2）对PHP 7+的兼容性很差，尤其是StreamWrapper的stat调用逻辑（file_exists、filesize底层都依赖这个）：

• 先检查你用的SDK版本：执行composer show aws/aws-sdk-php查看版本号，如果低于3.100，建议升级到适配PHP 7.2的最新兼容版本，很多这类跨版本问题都是SDK兼容不足导致的。

2. IAM角色缺失s3:ListBucket权限 #

划重点！虽然你说S3客户端能正常工作，但要注意：如果EC2用IAM角色授权，file_exists这类函数需要s3:ListBucket权限，而不仅仅是s3:GetObject。因为file_exists需要先列出桶内对应前缀的对象来确认存在，只给读取对象的权限是不够的：

• 验证方法：在EC2上用AWS CLI执行aws s3 ls s3://my-bucket/a-prefix/another-prefix/，如果能看到目标PDF文件，说明列表权限没问题；如果报错，就需要给IAM角色添加s3:ListBucket权限（注意要限定到对应的桶和前缀，不要给全桶权限）。

3. PHP配置禁用了相关函数 #

检查EC2的php.ini，看看是否把file_exists、stat或者filesize加入了disable_functions列表：

• 执行php -i | grep disable_functions查看禁用的函数，确保这些关键函数不在里面。
• 如果被禁用了，修改php.ini移除对应的条目，然后重启PHP-FPM或者Apache（根据你的Web服务类型）。

4. 流包装器注册时机或有效性问题 #

PHP 7.2对流包装器的注册时机要求更严格，可能存在注册后被意外覆盖或者未及时生效的情况：

• 把$this->s3Client->registerStreamWrapper();提前到代码最开头，确保在调用file_exists之前完成注册。
• 用下面的代码验证流包装器是否真的注册成功：

  var_dump(in_array('s3', stream_get_wrappers()));
  

  如果返回false，说明注册过程有错误，建议开启PHP错误日志，看看有没有被忽略的警告信息（比如SDK初始化失败）。

5. S3对象的存储类或ACL限制 #

虽然本地能访问，但EC2环境可能遇到对象存储类或权限的限制：

• 确认目标对象的存储类不是Glacier或Glacier Flexible Retrieval这类归档存储，这类对象无法直接用file_exists检测，需要先恢复到可读取状态。
• 检查对象的ACL权限，确保EC2的IAM角色拥有读取该对象的权限（有时候桶权限开了，但对象本身的ACL可能限制了访问）。

我之前碰到过最常见的情况就是IAM角色缺了s3:ListBucket权限，加上之后file_exists就正常返回true了，你可以先从这个点排查试试。

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