如何在AWS Amplify的Next.js应用中安全访问AWS Secrets Manager密钥？

问题背景 #

需要在Next.js的AWS Amplify应用中安全访问敏感密钥，核心要求是不硬编码任何密钥，尝试通过amplify.yml调用AWS Secrets Manager中的密钥，再通过process.env在应用中使用。当前使用的amplify.yml配置如下：

version: 1
env:
  variables:
    secrets:
      # SECRET_KEY_NAME defined in secrets manager
        MY_SECRET_KEY: SECRET_KEY_NAME 
frontend:
  phases:
    preBuild:
      commands:
        - export MY_SECRET_VALUE=$(aws secretsmanager get-secret-value --secret-id ${env.MY_SECRET_KEY} --query SecretString --output text)
        - echo "MY_SECRET_KEY=${MY_SECRET_VALUE}" >> .env
        - yarn install
    build:
      commands:
        - yarn run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

部署后访问应用URL出现XML错误（提示：此XML文件似乎没有关联的样式信息，下面显示文档树）。

错误原因分析 #

1. amplify.yml配置格式错误：secrets字段不能嵌套在env.variables下，Amplify的秘密变量需要直接定义在env.secrets层级中。
2. 手动调用AWS CLI的风险：自己执行aws secretsmanager命令需要确保Amplify构建角色有足够权限，一旦权限不足或命令执行失败，会导致构建中断，最终返回错误的XML响应（而非正常的Next.js资源）。
3. 构建命令顺序问题：yarn install的位置可能导致依赖安装时.env文件还未生成，不过这不是核心问题，主要还是配置格式和权限问题。

解决方案步骤 #

1. 给Amplify构建角色添加Secrets Manager访问权限

• 登录AWS IAM控制台，找到你的Amplify应用对应的构建角色（命名格式通常为amplify-<应用名>-<环境名>-<随机字符串>-role）。
• 为该角色添加SecretsManagerReadOnlyAccess权限策略（如果需要更精细的权限，可自定义策略仅允许访问指定的密钥ID）。

2. 修正amplify.yml配置

Amplify支持直接从Secrets Manager注入秘密变量到构建环境，无需手动调用CLI，修正后的配置如下：

version: 1
env:
  secrets:
    # 直接关联Secrets Manager中的密钥ID
    MY_SECRET_KEY: "SECRET_KEY_NAME"
frontend:
  phases:
    preBuild:
      commands:
        # 将秘密变量写入.env文件，供Next.js构建使用
        - echo "MY_SECRET_KEY=${secrets.MY_SECRET_KEY}" >> .env
        - yarn install
    build:
      commands:
        - yarn run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

3. 正确在Next.js中使用变量

• 服务端场景（API路由、服务端组件）：直接使用process.env.MY_SECRET_KEY即可，这些变量不会被暴露到客户端。
• 客户端场景（客户端组件）：需要将变量名改为NEXT_PUBLIC_MY_SECRET_KEY（对应修改amplify.yml中的密钥名和.env中的写入内容），然后在客户端代码中使用process.env.NEXT_PUBLIC_MY_SECRET_KEY。

4. 排查构建日志

如果部署后仍有问题，进入Amplify控制台的部署详情，查看preBuild和build阶段的日志，确认是否存在密钥获取失败、权限不足或构建报错的情况——这些是导致XML错误的根本原因（构建失败后Amplify会返回错误页面的XML响应）。

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