AWS CDK集成CloudFront+API Gateway+S3返回500错误{message: null}排查

以下是导致500错误（返回{message: null}）的核心问题及对应修复：

1. S3资源权限范围不足 #

当前角色仅授权了S3桶的ARN，但S3:GetObject（你代码中写的s3:Get是错误动作名）需要对象级别的权限，访问具体文件时会触发权限错误，进而导致API Gateway返回500。

修正代码：

role.addToPolicy(new PolicyStatement({
    resources: [`${this.props.stageConfig.s3BucketArn}/*`], // 添加/*覆盖桶内所有对象
    actions: ["s3:GetObject"], // 修正为标准动作名
}))

2. S3 Integration缺失关键配置 #

对接S3的AWS Integration需要指定区域，同时添加请求传递行为，避免参数丢失；另外未配置错误响应处理，导致集成返回异常时API Gateway返回默认空消息500。

修正代码：

const s3Integration = new AwsIntegration({
    service: "s3",
    region: this.props.stageConfig.region, // 指定S3所在区域
    integrationHttpMethod: "GET",
    path: `bookmarked-${this.props.stage}-storage/{folder}/{key}`,
    options: {
        credentialsRole: role,
        passthroughBehavior: PassthroughBehavior.WHEN_NO_TEMPLATES, // 确保请求参数正确传递
        integrationResponses: [
            {
                statusCode: "200",
                responseParameters: {
                    "method.response.header.Content-Type": "integration.response.header.Content-Type",
                },
            },
            // 添加404错误响应处理
            {
                statusCode: "404",
                selectionPattern: "404",
                responseParameters: {
                    "method.response.header.Content-Type": "'application/json'",
                },
                responseTemplates: {
                    "application/json": JSON.stringify({ message: "资源不存在" }),
                },
            },
            // 添加500错误响应处理
            {
                statusCode: "500",
                selectionPattern: "500",
                responseParameters: {
                    "method.response.header.Content-Type": "'application/json'",
                },
                responseTemplates: {
                    "application/json": JSON.stringify({ message: "服务器内部错误" }),
                },
            },
        ],
        requestParameters: {
            "integration.request.path.folder": "method.request.path.folder",
            "integration.request.path.key": "method.request.path.key",
        },
    }
})

3. API Gateway方法响应未覆盖错误状态码 #

当前仅配置了200的方法响应，当集成返回404/500时，API Gateway找不到对应响应规则，会返回默认的{message: null}500错误。

修正代码：

.addMethod('GET', s3Integration, {
    methodResponses: [
        {
            statusCode: '200',
            responseParameters: {
                'method.response.header.Content-Type': true
            },
        },
        {
            statusCode: '404',
            responseParameters: {
                'method.response.header.Content-Type': true
            },
        },
        {
            statusCode: '500',
            responseParameters: {
                'method.response.header.Content-Type': true
            },
        },
    ],
    // 其他原有配置保持不变
})

4. 自定义授权器返回格式验证 #

确保授权器Lambda返回符合API Gateway要求的格式，必须包含principalId和policyDocument，示例正确返回：

{
  "principalId": "user_identifier",
  "policyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Action": "execute-api:Invoke",
        "Effect": "Allow",
        "Resource": "arn:aws:execute-api:REGION:ACCOUNT_ID:API_ID/STAGE/GET/*"
      }
    ]
  }
}

返回格式错误会直接触发API Gateway 500错误。

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