如何在PHP版App Engine中获取Cloud Storage存储桶指定目录的子目录列表

在App Engine上跑的PHP应用要获取Google Cloud Storage（GCS）指定目录下的子目录列表？其实核心得先明白GCS的本质——它是扁平化存储，没有真正的“目录”，所谓的目录都是靠对象名里的/前缀模拟出来的。下面一步步教你实现：

1. 安装GCS PHP客户端库 #

首先得把官方的客户端库加到项目里，用Composer就行：

composer require google/cloud-storage

要是你用的是App Engine标准环境，部署的时候只要提交了composer.json和composer.lock，依赖会自动安装，不用额外操作。

2. 初始化客户端并关联存储桶 #

在App Engine上，应用会自动用默认的服务账号，不用手动配置密钥文件。直接初始化客户端并指定你的存储桶：

require __DIR__ . '/vendor/autoload.php';

use Google\Cloud\Storage\StorageClient;

// 初始化GCS客户端
$storage = new StorageClient();
// 替换成你的存储桶名称
$bucketName = 'your-bucket-name';
$bucket = $storage->bucket($bucketName);

3. 提取指定目录的子目录列表 #

关键技巧是调用listObjects时，指定prefix（你的目标目录，必须以/结尾）和delimiter为/。这样GCS服务端会自动帮你分组，返回的prefixes字段就是所有直接子目录的列表：

// 替换成你要查询的目标目录，记得结尾加/
$targetDir = 'docs/reports/';

// 配置查询参数：指定前缀+用/分隔
$options = [
    'prefix' => $targetDir,
    'delimiter' => '/'
];

// 拉取目录下的内容
$objects = $bucket->listObjects($options);

// 提取所有子目录前缀
$subDirPrefixes = $objects->prefixes();

// 可选：清理前缀，只保留子目录名称（比如把docs/reports/2024/变成2024）
$cleanedSubDirs = array_map(function ($prefix) use ($targetDir) {
    return rtrim(str_replace($targetDir, '', $prefix), '/');
}, $subDirPrefixes);

// 输出结果
print_r($cleanedSubDirs);

4. 配置权限 #

确保App Engine的默认服务账号（格式是[你的项目ID]@appspot.gserviceaccount.com）有足够权限列出存储桶内容。最简单的方式是给这个账号加Storage Object Viewer角色，或者更细粒度的storage.objects.list权限——前者已经包含后者的权限。

• GCS没有真实目录：所有对象都是平级存储的，“目录”只是对象名里的/分隔前缀，比如docs/reports/2024/代表所有以该字符串开头的对象。
• 用delimiter更高效：不用自己遍历所有对象再筛选，GCS服务端直接返回符合条件的子前缀，速度更快。
• 空目录处理：如果目标目录不存在或者没有子目录，$subDirPrefixes会是空数组，你可以根据业务逻辑做相应处理。

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