Amplify构建命令中无法访问process.env.secrets的问题排查

核心问题定位 #

Amplify构建环境不会自动将SSM参数存储的密钥注入到process.env，也没有$SECRETS/$PROCESS_ENV_SECRETS这类默认可用的变量，必须通过手动配置权限+构建脚本读取的方式获取密钥。

具体解决方案 #

1. 配置Amplify服务角色权限

确保Amplify的服务IAM角色拥有读取目标SSM参数的权限：

• 找到Amplify应用关联的IAM角色（控制台→IAM→角色→搜索amplify-{your-app-id}-{env}-role）
• 给角色添加内联策略，权限选择ssm:GetParameter，资源指定你的参数路径：

  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Action": "ssm:GetParameter",
              "Resource": "arn:aws:ssm:{region}:{account-id}:parameter/amplify/{my-app-id-here}/dev/API_KEY"
          }
      ]
  }
  

2. 修改Amplify构建脚本读取密钥

在Amplify控制台的「构建设置」中，编辑amplify.yml，在preBuild阶段通过AWS CLI读取SSM参数并写入.env.local：

version: 1
frontend:
  phases:
    preBuild:
      commands:
        # 读取SSM参数并写入.env.local
        - API_KEY=$(aws ssm get-parameter --name "/amplify/{my-app-id-here}/dev/API_KEY" --with-decryption --query "Parameter.Value" --output text)
        - echo "API_KEY=$API_KEY" >> .env.local
        # 调试用：确认密钥已写入（构建日志可查看）
        - cat .env.local
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

注意：如果你的API_KEY需要在Next.js客户端组件中使用，必须给变量加上NEXT_PUBLIC_前缀，修改写入命令为：

- echo "NEXT_PUBLIC_API_KEY=$API_KEY" >> .env.local

3. 验证构建日志

部署后查看构建日志，确认preBuild阶段的cat .env.local输出包含正确的API_KEY值；同时可以在build阶段添加printenv命令，查看所有环境变量是否符合预期。

4. 排查常见错误点

• 确认SSM参数路径完全匹配（包括app-id、环境名dev，注意大小写）
• 如果参数是加密存储的，必须加上--with-decryption参数，否则读取到的是加密字符串
• 服务器端使用的变量不需要NEXT_PUBLIC_前缀，但只能在getServerSideProps、API路由等服务器端代码中读取

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