boto3操作S3传入Prefix列表报参数类型无效错误的解决方案

S3 ListObjectsV2 接口的 Prefix 参数原生仅支持字符串类型，不接受数组入参，直接传入前缀列表会触发参数校验报错。

报错核心原因：Invalid type for parameter Prefix, valid types: <class 'str'>

不推荐全桶列举后本地过滤前缀的方案：如果桶内非目标路径的对象占比高，会产生大量无效API请求，耗时和请求成本都会显著升高。最优思路是针对每个目标前缀单独发起列举请求，再合并结果，根据数据量大小可以选择串行或并发实现。

基础串行实现 #

适合前缀数量少、单前缀下对象量不大的场景，逻辑简单无额外依赖：

import boto3

s3 = boto3.resource('s3')
my_bucket = s3.Bucket('database_buckets')
# 统一管理所有目标前缀，支持任意数量扩展
target_prefixes = ["db/", "db1/", "db2/"] # 补充你的30+个文件夹前缀即可

for prefix in target_prefixes:
    for object_summary in my_bucket.objects.filter(Prefix=prefix):
        print(object_summary.key)

注：原代码存在导入笔误，import boto 需要修正为 import boto3。

高并发高效实现 #

适合前缀多、单前缀下对象量大的场景，S3列举属于IO密集型操作，多线程并发可以大幅提升整体列举速度，无额外第三方依赖：

import boto3
from concurrent.futures import ThreadPoolExecutor, as_completed

def fetch_prefix_objects(bucket_name: str, prefix: str) -> list[str]:
    """列举单个前缀下的所有对象key"""
    s3 = boto3.resource('s3')
    bucket = s3.Bucket(bucket_name)
    return [obj.key for obj in bucket.objects.filter(Prefix=prefix)]

if __name__ == "__main__":
    TARGET_BUCKET = "database_buckets"
    TARGET_PREFIXES = ["db/", "db1/", "db2/"] # 替换为你的所有目标前缀
    MAX_WORKERS = 10 # 线程数建议10-20即可，过高容易触发S3接口限流
    all_object_keys = []

    with ThreadPoolExecutor(max_workers=MAX_WORKERS) as executor:
        task_map = {
            executor.submit(fetch_prefix_objects, TARGET_BUCKET, prefix): prefix
            for prefix in TARGET_PREFIXES
        }
        for future in as_completed(task_map):
            current_prefix = task_map[future]
            try:
                prefix_keys = future.result()
                all_object_keys.extend(prefix_keys)
                # 可直接实时处理返回的key，无需等待所有任务完成
                for key in prefix_keys:
                    print(key)
            except Exception as e:
                print(f"列举前缀 {current_prefix} 失败: {str(e)}")
    
    # 所有匹配的对象key最终汇总在all_object_keys变量中

• 如果不需要递归获取子文件夹下的内容，只需要当前前缀下的直接子项，可以在filter方法中传入Delimiter='/'参数。
• 线程数不要设置过高，S3 List类接口默认账户级限流为每秒3500次请求，普通场景10-20线程足够覆盖30+前缀的快速列举需求，避免触发429限流错误。
• 如果单前缀下对象数量超过1000个，boto3会自动处理分页，不需要手动写分页逻辑。

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