本教程详细介绍了如何利用 AWS SDK for PHP，通过巧妙结合 `Prefix` 和 `Delimiter` 参数，高效地从 Amazon S3 存储桶中仅获取指定路径下的第一层对象（包括文件和模拟目录）。文章将提供具体的代码示例，并解释如何解析返回结果以区分实际文件和子目录，确保开发者能够准确实现单层对象列表的需求，避免不必要的递归操作。
理解 S3 存储桶的层级结构与列表需求
Amazon S3 存储桶本身是一个扁平的存储空间，但通过对象键（Key）中的斜杠（/）可以模拟出目录结构。在实际应用中，我们经常需要像文件系统一样，只查看某个“目录”下的直接子文件和子目录，而不希望列出所有深层嵌套的对象。例如，如果你的 S3 存储桶中有以下对象键：
- public/uploads/test_company/test1
- public/uploads/test_company/test2
- public/uploads/test_company/test1/test.txt
当你希望获取 public/uploads/test_company/ 路径下的第一层内容时，理想的结果是只得到 public/uploads/test_company/test1 和 public/uploads/test_company/test2，而忽略 public/uploads/test_company/test1/test.txt。
核心参数：Prefix 与 Delimiter
AWS S3 API 提供了 listObjects (或 listObjectsV2) 方法来检索存储桶中的对象。要实现单层列表，我们需要利用其两个关键参数：Prefix 和 Delimiter。
立即学习“PHP免费学习笔记（深入）”；
- Prefix (前缀): 此参数用于筛选以指定字符串开头的所有对象。例如，设置 Prefix = 'public/uploads/test_company/' 将只返回所有以 public/uploads/test_company/ 开头的对象。
-
Delimiter (分隔符): 这是实现单层列表的关键。当指定 Delimiter 时，S3 会将所有包含该分隔符且在 Prefix 范围内的对象进行分组。它不会返回包含分隔符的完整对象键，而是返回两类信息：
- Contents: 直接位于指定 Prefix 下且不包含 Delimiter 的对象。
- CommonPrefixes: 模拟的子目录。这些是 Prefix 后第一个 Delimiter 之前的部分，代表了下一级目录的名称。
通过同时设置 Prefix 和 Delimiter = '/'，S3 API 能够智能地返回指定路径下的直接文件和下一级目录。
PHP 实现单层对象列表
使用 AWS SDK for PHP 3.x，我们可以通过 S3Client 的 listObjects 方法来实现。
首先，确保你的 PHP 项目中已经安装了 AWS SDK：
composer require aws/aws-sdk-php
接下来，以下是一个 PHP 代码示例，展示如何获取 public/uploads/test_company/ 路径下的第一层对象：
<?php
require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;
// 1. 配置 S3 客户端
// 确保你的 AWS 凭证已通过环境变量、配置文件或直接在代码中配置
// 例如：AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY
$s3Client = new S3Client([
'region' => 'your-aws-region', // 例如 'us-east-1'
'version' => 'latest',
// 如果需要，可以在这里指定凭证，但推荐使用环境变量或IAM角色
/*
'credentials' => [
'key' => 'YOUR_AWS_ACCESS_KEY_ID',
'secret' => 'YOUR_AWS_SECRET_ACCESS_KEY',
]
*/
]);
$bucketName = 'your-s3-bucket-name';
$targetPrefix = 'public/uploads/test_company/'; // 注意以斜杠结尾，表示一个目录
try {
// 2. 调用 listObjects 方法，设置 Prefix 和 Delimiter
$result = $s3Client->listObjects([
'Bucket' => $bucketName,
'Prefix' => $targetPrefix,
'Delimiter' => '/', // 关键：指定斜杠作为分隔符
// 'MaxKeys' => 100, // 可选：限制返回的最大对象数量
]);
echo "Listing objects under: s3://{$bucketName}/{$targetPrefix}\n";
echo "---------------------------------------------------\n";
// 3. 处理返回结果
// 3.1 打印直接位于当前前缀下的文件 (Contents)
if (isset($result['Contents'])) {
foreach ($result['Contents'] as $object) {
// 确保只打印当前层级的文件，不包括子目录本身作为文件
// S3 返回的 Key 会包含 Prefix，所以需要检查
$keyWithoutPrefix = substr($object['Key'], strlen($targetPrefix));
if (!empty($keyWithoutPrefix) && strpos($keyWithoutPrefix, '/') === false) {
echo "File: " . $object['Key'] . " (Size: " . $object['Size'] . " bytes)\n";
}
}
} else {
echo "No direct files found at this level.\n";
}
// 3.2 打印子目录 (CommonPrefixes)
if (isset($result['CommonPrefixes'])) {
foreach ($result['CommonPrefixes'] as $commonPrefix) {
// CommonPrefixes 已经是下一级目录的完整路径，以斜杠结尾
echo "Directory: " . $commonPrefix['Prefix'] . "\n";
}
} else {
echo "No subdirectories found at this level.\n";
}
echo "---------------------------------------------------\n";
} catch (AwsException $e) {
// 捕获并处理 AWS SDK 异常
echo "Error listing objects: " . $e->getMessage() . "\n";
} catch (Exception $e) {
// 捕获其他通用异常
echo "An unexpected error occurred: " . $e->getMessage() . "\n";
}
?>示例输出（基于问题描述的键）：
假设你的 S3 存储桶中有以下对象：
- public/uploads/test_company/test1
- public/uploads/test_company/test2
- public/uploads/test_company/test1/test.txt
- public/uploads/test_company/another_file.pdf
当 targetPrefix 设置为 public/uploads/test_company/ 时，你可能会得到类似这样的输出：
Listing objects under: s3://your-s3-bucket-name/public/uploads/test_company/ --------------------------------------------------- File: public/uploads/test_company/another_file.pdf (Size: XXX bytes) Directory: public/uploads/test_company/test1/ Directory: public/uploads/test_company/test2/ ---------------------------------------------------
请注意，test1 和 test2 在 S3 中实际上是对象键的一部分，但由于 Delimiter 的作用，它们被识别为 CommonPrefixes，模拟了目录。如果 public/uploads/test_company/test1 实际上是一个零字节文件，它会出现在 Contents 中，而 public/uploads/test_company/test1/ 作为一个 CommonPrefix 出现。
注意事项与最佳实践
Prefix 的结尾斜杠: 强烈建议 Prefix 以斜杠 / 结尾，这明确表示你正在查找一个“目录”下的内容。如果 Prefix 不以斜杠结尾，例如 public/uploads/test_company，那么 S3 会返回所有以该字符串开头的对象，包括 public/uploads/test_company_backup 等，这可能不是你期望的结果。
-
分页处理: 对于包含大量对象的存储桶，listObjects 的结果是分页的。默认情况下，MaxKeys 可能限制为 1000 个结果。如果返回结果中存在 IsTruncated 字段且为 true，则表示还有更多结果。你需要使用 Marker (或 ContinuationToken 对于 listObjectsV2) 参数进行后续请求来获取所有数据。
$marker = null; do { $params = [ 'Bucket' => $bucketName, 'Prefix' => $targetPrefix, 'Delimiter' => '/', 'Marker' => $marker, // 在后续请求中使用上一次的 NextMarker ]; $result = $s3Client->listObjects($params); // 处理 $result['Contents'] 和 $result['CommonPrefixes'] $marker = $result['NextMarker'] ?? null; // 获取下一次请求的 Marker } while ($marker); 错误处理: 务必在代码中加入 try-catch 块来捕获 AwsException 或其他潜在的异常，以提高代码的健壮性。
权限: 确保你的 AWS 凭证拥有对目标 S3 存储桶执行 s3:ListBucket 操作的权限。
listObjectsV2: AWS 推荐使用 listObjectsV2 方法，它提供了更现代的翻页机制 (ContinuationToken)。其参数和用法与 listObjects 类似。
总结
通过精确设置 Prefix 和 Delimiter 参数，AWS SDK for PHP 提供了强大而灵活的方式来控制 S3 对象列表的行为。这种方法不仅能帮助你高效地获取指定路径下的单层对象，还能清晰地区分文件和模拟目录，从而更好地管理和展示 S3 存储桶中的内容。理解并熟练运用这两个参数是进行 S3 开发的关键技能之一。
