AWS Amplify CLI 在 GitHub Actions 中拉取配置失败的解决方案

问题背景

在使用 AWS Amplify CLI 时，开发者可能会遇到在 GitHub Actions 工作流中执行 amplify pull 命令失败的情况。特别是在 Ubuntu 环境中，当尝试以无头(headless)模式拉取配置时，命令会卡在"Opening link"步骤，无法自动完成认证流程。

问题分析

这个问题主要源于两个关键因素：

1. Amplify Studio 认证机制：当项目中启用了 Amplify Studio 功能时，CLI 会默认使用 Studio 进行认证，这需要人工交互来完成验证流程。

2. 临时凭证支持不足：Amplify CLI 当前版本(12.10.1)对临时凭证的支持存在限制，特别是在 useProfile 设置为 false 时，无法正确处理通过环境变量传递的 AWS 凭证。

解决方案

方案一：禁用 Amplify Studio 并使用 AWS 配置文件

1. 在 AWS Amplify 控制台中禁用 Studio 功能
2. 在 GitHub Actions 工作流中创建临时 AWS 配置文件

aws configure set aws_access_key_id $AWS_ACCESS_KEY_ID
aws configure set aws_secret_access_key $AWS_SECRET_ACCESS_KEY 
aws configure set aws_session_token $AWS_SESSION_TOKEN
aws configure set default.region $AWS_REGION

3. 然后执行标准的 amplify pull 命令

方案二：使用 Headless 模式参数（支持启用 Studio）

对于需要保留 Studio 功能的项目，可以使用 JSON 格式的参数直接配置：

AWSCLOUDFORMATIONCONFIG="{
\"configLevel\":\"general\",
\"useProfile\":false,
\"profileName\":\"${AWS_PROFILE:-default}\",
\"region\":\"$AWS_REGION\"
}"

AMPLIFY="{
\"projectName\":\"项目名称\",
\"appId\":\"$AMPLIFY_APP_ID\",
\"envName\":\"$AMPLIFY_STAGE\",
\"defaultEditor\":\"none\"
}"

PROVIDERS="{
\"awscloudformation\":$AWSCLOUDFORMATIONCONFIG
}"

amplify pull \
--amplify $AMPLIFY \
--providers $PROVIDERS \
--yes

技术要点

1. 凭证处理：Amplify CLI 对临时凭证的处理方式与其他 AWS 服务不同，需要特别注意凭证的传递方式。

2. 环境变量验证：在脚本中应当验证所有必要的环境变量是否已设置，避免因缺失变量导致的失败。

3. 区域配置：确保 AWS 区域配置与 Amplify 项目设置一致，避免跨区域访问问题。

最佳实践建议

1. 对于自动化流程，建议优先考虑禁用 Studio 功能以简化认证流程。

2. 在 CI/CD 环境中使用 Amplify CLI 时，应当充分测试各种边界情况，包括凭证过期、权限不足等场景。

3. 考虑将 Amplify 配置步骤封装为可复用的 GitHub Actions 自定义步骤，提高工作流可维护性。

通过以上解决方案，开发者可以成功地在 GitHub Actions 工作流中实现 Amplify 配置的自动化拉取，无论是启用还是禁用 Studio 功能的环境下都能正常工作。