boto3调用S3列表接口无法返回GUI上传的新文件问题排查

这个问题不需要清理任何缓存解决，默认配置下boto3本身不会对S3列表查询结果做本地缓存，每次迭代bucket.objects.filter都会真实发起API请求，不存在本地缓存旧结果不刷新的情况。
出现新上传文件无法被列出、存量旧文件正常返回的核心原因是S3服务端的接口一致性特性，和boto3客户端配置无关。

• S3的接口分两类一致性保证：针对单个确定对象Key的操作（比如上传完成后控制台查这个文件、直接调用HeadObject/GetObject查已知Key）是强一致性，只要控制台显示上传完成，这类操作立刻就能拿到正确的文件状态、文件内容。
• 针对前缀遍历的列表类接口（也就是你代码里用的ListObjectsV2，对应bucket.objects.filter的底层实现），在分布式副本未完成全量同步时，会出现短暂的结果不一致：新上传的对象元数据需要几秒到几十秒不等的时间同步到所有S3存储节点，列表请求如果路由到还没同步到新元数据的节点，返回结果里就不会包含刚上传的文件。
• 存在时间较长的文件已经完成全节点元数据同步，不管请求路由到哪个节点都能被查到，所以每次列表都能稳定返回。

• 如果业务允许短暂延迟：在上传操作完成后加3-10秒的等待时间再发起列表查询，或者给列表逻辑加重试，轮询直到目标文件出现在结果中再执行下载。
• 如果你能拿到新上传文件的完整对象Key：完全不需要走前缀遍历逻辑，直接调用s3_client.download_file(bucket_name, 完整对象key, 本地保存路径)即可，单Key操作是强一致性的，上传完成后立刻调用就能正常下载，不会出现找不到文件的问题。
• 排障时不要做无效操作：重装boto3、清空本地临时文件、重建客户端实例都不会改变S3服务端的返回结果，对解决这个问题没有任何帮助。

补充：如果等待超过1分钟新文件仍然无法在列表中返回，再检查你配置的Prefix是否和新上传文件的路径完全匹配，注意S3没有真实目录结构，Prefix是字符串前缀匹配，末尾漏写/、多写斜杠都会导致匹配异常，但这类问题通常会导致所有同路径文件都查不到，不会只影响新上传的文件。

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