列举存储空间中的文件

更新时间：2026-09-23

BOS Python SDK 支持通过简单列举与参数列举两种方式列出 Bucket 中的 Object，还可借助 prefix、delimiter 参数模拟文件夹结构。

运行以下示例前，请先参考初始化完成 BOS Client 初始化，并将示例中的 bucket_name 替换为实际值。

简单列举

列举指定 Bucket 中的 Object：

                Python
                
                response = bos_client.list_objects(bucket_name)
for obj in response.contents:
    print(obj.key)

注意：

默认情况下，若 Bucket 中的 Object 数量大于 1000，单次仅返回 1000 个 Object，此时返回结果的 is_truncated 为 True，并返回 next_marker 作为下次读取的起点。

若需读取全部 Object，可使用 marker 参数分次读取，或直接使用 list_all_objects。

list_all_objects 返回一个生成器（Generator），会自动翻页，不受单次最多返回 1000 条的限制：

                Python
                
                for obj in bos_client.list_all_objects(bucket_name):
    print(obj.key)

通过参数列举

list_objects 的可选参数：

参数	类型	说明
`prefix`	str	限定返回的 Object Key 必须以该前缀开头。
`delimiter`	str	用于对 Object 名字分组的字符。名字包含指定前缀、且在前缀之后第一次出现 `delimiter` 之前的部分作为一组元素返回到 `common_prefixes` 中。
`max_keys`	int	单次返回 Object 的最大数目，不能超过 1000，默认为 1000。
`marker`	str	从该 marker 之后按字典序返回结果。

注意：

仅使用 prefix 查询时，返回结果中仍会包含以该前缀命名的 Object 本身。

prefix 与 delimiter 组合查询时，子目录会返回在 common_prefixes 中。

指定最大返回条数

                Python
                
                max_keys = 500
response = bos_client.list_objects(bucket_name, max_keys=max_keys)
for obj in response.contents:
    print(obj.key)

返回指定前缀的 Object

                Python
                
                prefix = "test"
response = bos_client.list_objects(bucket_name, prefix=prefix)
for obj in response.contents:
    print(obj.key)

从指定 Object 之后返回

                Python
                
                marker = "example-object-key"
response = bos_client.list_objects(bucket_name, marker=marker)
for obj in response.contents:
    print(obj.key)

分页获取所有 Object

                Python
                
            

                is_truncated = True
max_keys = 500
marker = None
while is_truncated:
    response = bos_client.list_objects(bucket_name, max_keys=max_keys, marker=marker)
    for obj in response.contents:
        print(obj.key)
    is_truncated = response.is_truncated
    marker = getattr(response, 'next_marker', None)
            

list_objects 返回的解析类中可供调用的字段：

字段	说明
`name`	Bucket 名称。
`prefix`	本次查询使用的前缀。
`marker`	本次查询的起点。
`max_keys`	本次请求返回的最大数目。
`is_truncated`	是否还有未返回的结果。`False` 表示已返回全部结果，`True` 表示还有剩余结果。
`contents`	Object 列表容器。
`key`	Object 名称。
`last_modified`	Object 最后一次被修改的时间。
`etag`	Object 的 HTTP 协议实体标签。
`size`	Object 内容大小（字节数）。
`storage_class`	Object 的存储类型。
`owner`	Object 所属 Bucket 的用户信息，含 `id`、`display_name`。
`next_marker`	当 `is_truncated` 为 `True` 时返回，作为下次查询的 `marker`。
`common_prefixes`	仅当指定 `delimiter` 时返回。

模拟文件夹功能

BOS 的存储结构中没有文件夹的概念，所有元素均以 Object 存储。所谓"文件夹"本质上是一个 size 为 0、以 / 结尾的 Object，控制台会将其以文件夹形式展示。通过 prefix 与 delimiter 的组合可以模拟文件夹：

将 prefix 设为某个目录名，可递归列出该目录下所有文件和子目录中的文件，均显示在 contents 中。
在此基础上把 delimiter 设为 /，则只列出该目录下的直接文件，直接子目录返回在 common_prefixes 中，更深层的内容不再展开。

假设 Bucket 中有 bos.jpg、fun/、fun/test.jpg、fun/movie/001.avi、fun/movie/007.avi 五个 Object，以 / 作为文件夹分隔符。

递归列出目录下所有文件

                Python
                
                prefix = "fun/"
response = bos_client.list_objects(bucket_name, prefix=prefix)
for obj in response.contents:
    print(obj.key)

输出：

Plain Text

1fun/
2fun/movie/001.avi
3fun/movie/007.avi
4fun/test.jpg

                Python
                
            

                delimiter = "/"
prefix = "fun/"
response = bos_client.list_objects(bucket_name, prefix=prefix, delimiter=delimiter)

print("Objects:")
for obj in response.contents:
    print(obj.key)

print("CommonPrefixes:")
for p in response.common_prefixes:
    print(p.prefix)
            

输出：

Plain Text

1Objects:
2fun/
3fun/test.jpg
4CommonPrefixes:
5fun/movie/

fun/movie/001.avi、fun/movie/007.avi 因属于 fun 下的 movie 子目录而不会被直接列出，movie 目录返回在 common_prefixes 中。

列举 Object 的存储属性

                Python
                
                response = bos_client.list_objects(bucket_name)
for obj in response.contents:
    print('object: {}, storage_class: {}'.format(obj.key, obj.storage_class))

方法说明

方法	返回值	说明
`bos_client.list_objects(bucket_name, ...)`	`BceResponse`	列举 Object，单次最多 1000 条。
`bos_client.list_all_objects(bucket_name, prefix=None, delimiter=None)`	`generator`	自动翻页列举全部 Object。

评价此篇文章

有帮助没帮助

获取预签名文件URL

Object权限控制

百度智能云

BOS 对象存储