火山引擎 GitHub Actions 结合对象存储与 CDN 部署静态网站

GitHub Actions

在项目的主目录中新建一个 .github/workflows/deploy.yml 文件，配置如下：

name: Deploy to Volcengine TOS
on:
  push:
    branches:
      - main
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    env:
      # Build-time env for Vite (optional)
      VITE_API_BASE_URL: ${{ secrets.VITE_API_BASE_URL }}
      # Volcengine TOS (S3-compatible) deploy config
      TOS_BUCKET: ${{ secrets.TOS_BUCKET }}
      TOS_REGION: ${{ secrets.TOS_REGION }}
      TOS_ENDPOINT: ${{ secrets.TOS_ENDPOINT }}
      # Credentials
      AWS_ACCESS_KEY_ID: ${{ secrets.VOLC_AK }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.VOLC_SK }}
      AWS_EC2_METADATA_DISABLED: "true"
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      - name: Install dependencies
        run: npm ci
      - name: Build project
        run: npm run build
        env:
          VITE_API_BASE_URL: ${{ secrets.VITE_API_BASE_URL }}
      - name: Sanity check build output contains API base
        run: |
          echo "Check if build still contains localhost:"
          grep -R "127.0.0.1:8080" -n dist/ && exit 1 || echo "OK: localhost not found"
      - name: Upload Vite build output (dist/) to TOS
        run: |
          aws s3 sync dist/ "s3://${TOS_BUCKET}/" \
            --endpoint-url "$TOS_ENDPOINT" \
            --region "$TOS_REGION" \
            --delete
      - name: Configure Static Website Hosting
        run: |
          aws s3 website "s3://${TOS_BUCKET}/" \
            --index-document index.html \
            --error-document index.html \
            --endpoint-url "$TOS_ENDPOINT" \
            --region "$TOS_REGION"

说明：

• 环境变量需在 GitHub Secrets 中配置。VOLC_AK 为访问密钥 ID，VOLC_SK 为密钥。
• 触发条件为推送到 main 分支时自动执行。
• --delete 参数会删除远程桶中本地不存在的文件，确保完全同步。
• 配置 TOS 桶为静态网站托管模式，index.html 作为默认首页和错误页面（适用于 SPA 应用路由）。

对象存储桶

创建一个桶（Bucket）作为对象存储。对象存储类似于网盘，存储的对象由 Key（名称）、Data（内容）和 Metadata 构成，通过 HTTP 访问。

• Endpoint：S3 兼容 Endpoint，用于 AWS S3 CLI / SDK 连接。
• Bucket 域名：用于浏览器访问或 CDN 回源。

CDN 配置

内容分发网络（CDN）将源站响应缓存至边缘节点，减少延迟。需配置回源 Host，即缓存未命中时请求源站的位置。

常见问题排查

若修改了后端 API 地址后刷新无效，可能是以下原因：

1. GitHub Actions 缓存：直接重跑 Job 可能读取旧的环境变量。建议提交空 Commit（使用 --allow-empty）以触发新流程。
2. 浏览器缓存：对比 curl 抓包与浏览器 Console 获取的资源，发现两者不一致。清除浏览器 Storage 无效。
3. CDN 缓存：需手动在 CDN 控制台进行刷新预热操作。

缓存控制

• 源站配置：在 YAML 中设置 --cache-control "no-cache, max-age=0"，规定源站表现，禁止任何缓存。
• CDN 配置：在 CDN 控制台单独配置缓存策略，覆盖 CDN 侧的缓存行为。