如何为部署在AWS S3的静态项目编写GitHub YML工作流实现PR预览构建

完整工作流配置（.github/workflows/pr-preview.yml） #

直接使用以下配置，根据项目技术栈调整对应命令：

name: PR Preview Build & Deploy

# PR打开、同步、重新触发时执行
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码
        uses: actions/checkout@v4

      # 安装依赖（根据项目替换，如yarn install、pip install等）
      - name: 安装项目依赖
        run: npm ci

      # 构建项目（替换为你的项目构建命令，如npm run build:preview）
      - name: 构建预览产物
        run: npm run build
        env:
          NODE_ENV: production

      # 配置AWS凭证
      - name: 配置AWS权限
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ secrets.S3_BUCKET_REGION }}

      # 上传到S3的PR专属目录
      - name: 部署到S3
        run: |
          aws s3 sync ./dist s3://${{ secrets.S3_BUCKET }}/pr-preview/pr-${{ github.event.number }} \
            --delete \
            --cache-control "max-age=31536000, public"
        # 注意：./dist替换为你的实际构建产物目录；pr-preview/pr-${PR号}用于区分不同PR的预览资源

      # CloudFront缓存失效（可选，需按需开启）
      - name: 刷新CloudFront缓存
        run: |
          aws cloudfront create-invalidation \
            --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
            --paths "/pr-preview/pr-${{ github.event.number }}/*"

      # 在PR中添加预览链接评论
      - name: 给PR添加预览链接
        uses: thollander/actions-comment-pull-request@v2
        with:
          message: |
            🚀 PR预览已生成！
            预览地址：https://${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }}.cloudfront.net/pr-preview/pr-${{ github.event.number }}/
            # 若使用S3静态域名，替换为：https://${{ secrets.S3_BUCKET }}.s3.${{ secrets.S3_BUCKET_REGION }}.amazonaws.com/pr-preview/pr-${{ github.event.number }}/
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

关键配置说明 #

• 触发规则：仅在PR的打开、代码同步、重新触发时执行，避免无效构建。
• 路径隔离：用pr-${{ github.event.number }}作为S3子目录，每个PR的预览资源独立存储，不会互相覆盖。
• 缓存策略：上传时设置cache-control，静态资源长期缓存，动态内容可调整缓存时长。
• 权限校验：确保AWS密钥拥有S3的上传/删除权限、CloudFront的缓存失效权限，可参考以下IAM策略：

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": ["s3:ListBucket", "s3:PutObject", "s3:DeleteObject"],
        "Resource": ["arn:aws:s3:::${你的S3桶名}", "arn:aws:s3:::${你的S3桶名}/*"]
      },
      {
        "Effect": "Allow",
        "Action": ["cloudfront:CreateInvalidation"],
        "Resource": ["arn:aws:cloudfront::${你的AWS账号ID}:distribution/${你的CloudFrontID}"]
      }
    ]
  }
  

常见问题排查 #

• 构建产物路径错误：确认./dist是项目实际的构建输出目录，比如部分项目是./build或./public。
• 预览地址无法访问：检查S3静态网站托管是否开启，或CloudFront的路径转发规则是否匹配/pr-preview/*。
• 权限不足：查看GitHub Actions日志中的AWS权限报错，调整IAM策略的资源范围。

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