AWS PHP SDK 必须安装 Common Runtime 吗

AWS Common Runtime（CRT）并非使用 AWS SDK for PHP 的全局强依赖；它仅在某些特定操作（例如调用 EventBridge 的 putEvents 并启用 Signature V4A、或使用 S3 多区域接入点签名）时才会强制要求。对日常大部分业务场景而言，完全可以在不安装 CRT 的前提下正常运行。

许多开发者在 Laravel 项目中集成 AWS PHP SDK 时，可能会遇到一个令人困惑的错误信息：AwsExceptionCommonRuntimeException: AWS Common Runtime for PHP is required to use Signature V4A。乍看起来，这个错误容易让人误以为整个 PHP SDK 已全面转向依赖 CRT，甚至需要在服务器上手动编译安装相关扩展。但实际上，这是一个精确的、按需触发的限制条件，而并非全局性硬性要求。换句话说，对于绝大多数应用场景，你完全不需要安装 CRT。

✅ 哪些场景下你 不需要 安装 CRT？

多数常用 AWS 服务，例如 S3 的文件上传与下载、DynamoDB 的数据增删改查、SQS 的消息收发、Lambda 函数调用以及 CloudWatch 日志写入等，默认均采用标准的 Signature Version 4（SigV4）签名协议。借助原生的 PHP cURL 或 Guzzle HTTP 客户端即可高效处理，完全无需 CRT 的介入。下面是一个具体的例子：

use AwsEventBridgeEventBridgeClient;

$client = new EventBridgeClient([
    'region' => 'us-east-1',
    'version' => '2015-10-07',
    'credentials' => [
        'key'    => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
    ],
]);

// ✅ 该操作不会触发 SigV4A，因此无需 CRT
$result = $client->listEventBuses();

注意，调用 listEventBuses 接口时毫无问题，不会触发任何与 CRT 相关的错误提示。

⚠️ 哪些场景下你 必须 安装 CRT？

截至目前（对应 AWS SDK for PHP v3.290 及以上版本），真正需要 CRT 支持的场景仅存在于以下两种情况：

• EventBridge 的 putEvents() 方法启用 TraceHeader 或实现跨账户事件投递——此类操作会用到 SigV4A 签名；
• S3 Multi-Region Access Points（MRAP）的请求签名。

如果你编写的代码没有主动启用这些高级特性，例如没有设置 'signature_version' => 'v4a' 配置项，或没有使用 MRAP 端点地址，那么通常该异常是由 SDK 自动降级失败或配置本身触发了不必要的选项导致的。此时应优先检查客户端配置，而不是急于部署 CRT 扩展。

? 推荐替代方案（避免安装 CRT）

鉴于绝大多数使用场景并不依赖 CRT，遇到报错时可以通过以下几种方式快速绕过：

1. 显式禁用 SigV4A（推荐）：在构造客户端时手动将签名版本指定为 v4：

   $client = new EventBridgeClient([
       'region' => 'us-east-1',
       'version' => '2015-10-07',
       'signature_version' => 'v4', // 强制使用传统 SigV4 签名
       'credentials' => new AwsCredentialsCredentials(
           env('AWS_ACCESS_KEY_ID'),
           env('AWS_SECRET_ACCESS_KEY')
       ),
   ]);

2. 确认凭证来源正确：确保凭证通过安全渠道注入，例如使用 .env 文件配合 config/aws.php 配置文件。凭证缺失时，SDK 可能自动回退到更高安全等级的签名流程，从而意外触发 CRT 需求：

   // config/aws.php
   'credentials' => [
       'key'    => env('AWS_ACCESS_KEY_ID'),
       'secret' => env('AWS_SECRET_ACCESS_KEY'),
   ],
   'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),

3. 升级 SDK 版本：v3.285 及后续版本已对 SigV4A 的触发逻辑进行了优化，不易因配置不当而误启动该签名。建议运行以下命令进行升级：

   composer update aws/aws-sdk-php

? 注意事项

• ❌ 不建议在 Docker 环境中盲目编译安装 awslabs/aws-crt-php 扩展，尤其在 Alpine 镜像中，极易出现 glibc 兼容性问题，增加排查难度；
• ✅ 应优先排查是否误开启了 v4a 签名模式，或调用了受限 API。大多数 Laravel 应用实际上对 CRT 没有刚性需求；
• ? 务必避免在代码中硬编码密钥。始终借助 IAM 角色（EC2/ECS）或环境变量，并通过 Laravel 配置抽象层统一管理凭证。

总而言之，AWS 并非刻意增加开发者的负担——它仅在极少数需要更强加密保证和跨区域一致性支持的场景下，才引入了 CRT 依赖。对于绝大多数 PHP 应用而言，只要能保持 SDK 版本更新、合理配置签名版本及凭证信息，即可实现零额外依赖、零编译、零运维成本的稳定对接，轻松使用 AWS 云服务。