AWS Amplify Next.js 应用中 S3 凭证错误的解决方案_技术教程

在 AWS Amplify 托管的 Next.js 应用中，当尝试上传文件到 S3 时，即使环境变量已正确配置，也可能遭遇 `CredentialsError: Missing credentials in config` 错误。此问题通常源于 Amplify 应用关联的 IAM 角色权限不足，而非 S3 客户端配置错误。解决方案涉及为 Amplify 的 IAM 角色（特别是未经身份验证的角色）添加 S3 操作的内联策略，并相应地配置 S3 存储桶策略，以确保应用程序具备必要的访问权限。

理解 AWS Amplify 中的凭证管理

在本地开发环境中，使用 process.env.ACCESS_KEY_AWS 和 process.env.SECRET_KEY_AWS 在 S3 客户端实例化时提供凭证通常是有效的。然而，当应用程序部署到 AWS Amplify 时，其凭证管理机制有所不同。Amplify 应用通常会利用在 amplify init 过程中设置的 IAM 角色来执行 AWS 服务操作。这意味着，即使您在 S3 客户端中显式传入 accessIdKey 和 secretAccessKey，Amplify 后端在执行操作时，很可能仍然会优先使用其关联的 IAM 角色凭证。因此，Missing credentials 错误往往是 IAM 角色权限不足的误导性提示。

常见排查与误区

在遇到此类问题时，开发者通常会检查以下几点：

环境变量配置： 确认 AWS 访问密钥和秘密密钥已在 Amplify 控制台正确设置，并通过构建配置传递给生产环境。
环境变量可访问性： 通过 console.log 验证应用程序代码能够访问这些环境变量。
S3 存储桶公共访问： 检查 S3 存储桶是否已设置为允许公共访问。
IAM 用户权限： 确认用于生成访问密钥的 IAM 用户拥有 AmazonS3FullAccess 等足够权限。

尽管这些检查是必要的，但对于 Amplify 环境中的特定问题，它们往往不足以解决 CredentialsError。核心问题在于 Amplify 应用所扮演的 IAM 角色。

解决方案：配置 IAM 角色和 S3 存储桶策略

解决此问题的关键在于为 Amplify 应用的 IAM 角色授予正确的 S3 权限，并确保 S3 存储桶策略允许这些操作。

1. 配置 Amplify 的 IAM 角色

首先，您需要识别 Amplify 应用所使用的 IAM 角色。对于不涉及 Cognito 身份验证的上传场景，通常是 Amplify 的“未经身份验证的角色”（Unauthenticated Role）。

步骤：

登录 AWS IAM 管理控制台。
导航到“角色”部分。
查找与您的 Amplify 应用相关的角色，特别是名称中可能包含 amplify 和 unauth 的角色（例如 amplify-YOUR_APP_NAME-YOUR_ENV-unauthRole）。
选择该角色，然后点击“添加内联策略”。
切换到 JSON 选项卡，并粘贴以下策略配置。请务必将 {BUCKET_NAME} 替换为您的 S3 存储桶名称。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::{BUCKET_NAME}/public/*"
            ],
            "Effect": "Allow"
        }
    ]
}

解释：

s3:PutObject：允许上传文件。
s3:GetObject：允许下载或读取文件。
s3:DeleteObject：允许删除文件。
arn:aws:s3:::{BUCKET_NAME}/public/*：此资源 ARN 限制了权限范围，仅允许对指定存储桶的 public/ 路径下的对象进行操作。您可以根据实际需求调整路径或范围。

2. 配置 S3 存储桶策略

除了 IAM 角色权限，S3 存储桶本身也需要有相应的策略来允许外部访问。

步骤：

登录 AWS S3 控制台。
选择您的存储桶。
导航到“权限”选项卡。
在“阻止公共访问（存储桶设置）”部分，确保已取消选中“阻止所有公共访问”或根据您的需求进行配置。
在“存储桶策略”部分，点击“编辑”，并粘贴以下策略配置。请务必将 {BUCKET_NAME} 替换为您的 S3 存储桶名称。

{
    "Version": "2012-10-17",
    "Id": "ExamplePolicy01",
    "Statement": [
        {
            "Sid": "ExampleStatement01",
            "Effect": "Allow",
            "Principal": {
                "AWS": "*"
            },
            "Action": [
                "s3:*"
            ],
            "Resource": [
                "arn:aws:s3:::{BUCKET_NAME}/*",
                "arn:aws:s3:::{BUCKET_NAME}"
            ]
        }
    ]
}

解释：

"Principal": {"AWS": "*"}：此策略允许所有 AWS 主体（包括匿名用户和经过身份验证的用户）执行指定操作。请注意，这会使您的存储桶内容公开可访问。在生产环境中，应根据实际安全需求，将 Principal 限制为特定的 IAM 角色或用户。
"Action": ["s3:*"]：允许对存储桶执行所有 S3 操作。出于安全考虑，建议将其限制为仅必要的最小权限，例如 s3:PutObject, s3:GetObject 等。
"Resource": [...]：指定策略生效的资源范围，包括存储桶本身及其内部的所有对象。

代码调整（可选）

完成上述 IAM 角色和 S3 存储桶策略配置后，您的 Next.js 应用中的 S3 实例化代码可能不再需要显式传入 accessIdKey 和 secretAccessKey。Amplify 应用将自动使用其关联 IAM 角色的凭证。

// 原始代码：
// const s3 = new S3({
//   accessIdKey: process.env.ACCESS_KEY_AWS,
//   secretAccessKey: process.env.SECRET_KEY_AWS,
// });

// 优化后（依赖Amplify IAM角色）：
const s3 = new S3({
  // 如果Amplify IAM角色已正确配置，这些可能不再需要
  // region: "sa-east-1", // 建议保留区域配置
});

为什么本地开发与生产环境行为不同？

本地开发环境通常直接使用您在 ~/.aws/credentials 或通过环境变量配置的 AWS 凭证，这些凭证通常与具有 AmazonS3FullAccess 权限的 IAM 用户关联。而 AWS Amplify 生产环境则依赖于为您的应用配置的 IAM 角色。如果该角色没有足够的 S3 权限，即使您的本地 IAM 用户有权限，生产环境也会失败。

注意事项与最佳实践

最小权限原则： 在配置 IAM 策略和存储桶策略时，始终遵循最小权限原则。只授予执行特定任务所需的最低权限，避免使用 s3:* 或 Principal: {"AWS": "*"}，除非您明确了解其安全影响并接受风险。
安全性： 如果您的应用需要上传用户文件，并希望这些文件保持私有，那么不应将存储桶设置为完全公共访问。应考虑使用 AWS Cognito 进行用户身份验证，并根据用户身份动态生成带有预签名 URL 的上传或下载链接，或者通过 IAM 策略精确控制每个用户的访问权限。
错误日志： 仔细检查 AWS CloudWatch 日志，它们是诊断生产环境中 AWS 服务相关问题的最重要工具。

通过正确配置 Amplify 应用的 IAM 角色和 S3 存储桶策略，您可以解决在 Next.js 应用中遇到的 CredentialsError，确保文件能够顺利上传到 S3。