如何通过GitHub Action在Vercel托管AsyncAPI生成的HTML文档？

一、先验证本地HTML生成流程 #

确保你能通过AsyncAPI正确生成HTML文档：

• 安装AsyncAPI CLI：npm install -g @asyncapi/cli
• 执行生成命令（替换./asyncapi.yaml为你的配置文件路径）：

  asyncapi generate fromTemplate ./asyncapi.yaml @asyncapi/html-template -o ./docs
  

  生成的HTML会输出到./docs目录，后续部署会用到这个目录。

二、配置Vercel部署规则 #

在项目根目录创建vercel.json文件，指定Vercel只部署生成的静态HTML：

{
  "buildCommand": "echo 'Using pre-generated AsyncAPI docs'",
  "outputDirectory": "./docs",
  "routes": [
    { "src": "/(.*)", "dest": "/index.html" }
  ]
}

这个配置告诉Vercel将docs目录作为静态资源根目录，所有请求都指向生成的index.html（适配单页HTML文档的路由）。

三、创建GitHub Action自动部署工作流 #

在项目的.github/workflows/目录下新建deploy-asyncapi-docs.yml文件，内容如下：

name: Deploy AsyncAPI Docs to Vercel

# 触发条件：主分支推送、PR合并到主分支
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
    types: [ closed ]
    if: github.event.pull_request.merged == true

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

      - name: 配置Node.js环境
        uses: actions/setup-node@v4
        with:
          node-version: '20' # 选择兼容AsyncAPI CLI的Node版本

      - name: 安装AsyncAPI CLI
        run: npm install -g @asyncapi/cli

      - name: 生成AsyncAPI HTML文档
        run: asyncapi generate fromTemplate ./asyncapi.yaml @asyncapi/html-template -o ./docs

      - name: 部署到Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod' # 如需部署预览环境可移除该参数
          working-directory: ./

四、配置GitHub Secrets #

在你的GitHub仓库中，进入「Settings → Secrets and variables → Actions」，添加以下3个密钥：

• VERCEL_TOKEN: 从Vercel账户设置（Settings → Tokens）生成的访问令牌
• VERCEL_ORG_ID: Vercel项目所属组织的ID（在Vercel项目设置的General页面可找到）
• VERCEL_PROJECT_ID: Vercel项目的ID（同样在项目General页面可找到）

五、验证自动部署流程 #

• 推送代码到主分支，或者合并PR到主分支，GitHub Action会自动执行文档生成和Vercel部署
• 部署完成后，可在Vercel项目页面查看状态，访问对应的域名即可查看最新的AsyncAPI文档

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