❌

普通视图

发现新文章，点击刷新页面。
昨天以前首页

构建 “按版本触发、自动发布、自动回写” 的前端组件发布流水线

✇掘金 前端
作者 雨夜寻晴天
2026年1月6日 11:33

一套工作流，统一发布多个仓库下的多个组件；以 “版本号变化” 为唯一触发；发布成功后自动回写配置并生成 PR。新增组件只需改两处配置，剩下交给 CI。

背景与目标

  • 前端组件分散在不同仓库，人工发布易错、流程冗长；
  • 需要 “改版本 → 自动构建发布 → 自动同步配置” 的一条龙流程；
  • 通过 GitHub Actions + 集中配置文件，搭建一套稳健、可扩展的发布流水线。

本文基于两份核心文件：

架构一览

  • 集中配置文件管理组件的构建/发布参数。
  • 工作流读取配置与触发输入，根据 “版本变化” 生成发布矩阵。
  • 按矩阵逐仓库逐组件执行构建与 npm publish。
  • 发布结束后自动回写工作流默认值与组件 current_version，并提自动合并 PR。

核心思想：

  • “版本号变化” 是唯一发布触发条件；
  • 配置集中在 components.json，组件级可覆盖仓库级默认值；
  • 发布完成后自动回写，确保 “配置=事实”。

核心文件与关键片段

工作流输入（workflow_dispatch）

on:
  workflow_dispatch:
    inputs:
      SEARCH_CHAT_VERSION: { description: 'search-chat Version', required: true, default: "1.3.10" }
      UI_WEB_CLI_VERSION: { description: 'ui-web-cli Version', required: true, default: "0.0.43" }
      FILTER_VERSION: { description: 'filter Version', required: true, default: "0.0.11" }
      SEARCH_RESULTS_VERSION: { description: 'search-results Version', required: true, default: "0.0.11" }
      ENTITY_UI_VERSION: { description: 'entity-ui Version', required: true, default: "0.0.10" }
      CUSTOM_ICONS_VERSION: { description: 'custom-icons Version', required: true, default: "0.0.10" }
      DROPDOWNLIST_VERSION: { description: 'dropdownlist Version', required: true, default: "1.3.5" }
      DATEPICKER_VERSION: { description: 'datepicker Version', required: true, default: "0.0.10" }
      AI_ANSWER_VERSION: { description: 'ai-answer Version', required: true, default: "0.0.1" }

命名约定：组件名通过 “全大写 + 短横线改下划线 + 后缀 _VERSION”生成输入键，例如 ai-answer → AI_ANSWER_VERSION。

组件集中配置（components.json）

{
  "ui-common": {
    "repo_private": false,
    "build_cmd": "pnpm build",
    "publish_cmd": "npm publish",
    "version_file": "package.json",
    "adapter_script": false,
    "components": {
      "ai-answer": {
        "current_version": "0.0.1",
        "work_dir": "packages/AIAnswer",
        "dist_dir": "packages/AIAnswer"
      }
    }
  }
}

说明：

  • work_dir 为构建发生地；
  • dist_dir 为 npm publish 的目录；
  • version_file 默认为 package.json，也可覆盖为 tsup.config.ts。

工作流执行路径与原理

1. 生成发布矩阵（prepare-matrix）

位置与逻辑：coco-app-web.yml

  • 遍历 components.json 的所有仓库与组件；
  • 将组件名映射为输入键（如 ai-answer → AI_ANSWER_VERSION）；
  • 对比输入版本与 current_version，不一致者纳入矩阵；
  • 输出矩阵 JSON 与 has_repos 标记。

优点：仅发布 “发生版本变化” 的组件，避免无效构建。

2. 构建与发布（publish）

位置与逻辑：coco-app-web.yml

  • checkout CI 仓库与目标仓库（支持私仓 SSH 私钥）。
  • 通过 jq 实现“组件优先、仓库兜底”的配置继承。
  • 写入版本：
    • 若 version_file 为 tsup.config.ts：用 sed 更新 version: "x.y.z"；
    • 否则用 jq 写 package.json 的 version 字段。
  • 在 work_dir 执行 pnpm install 与 build_cmd；
  • 进入 dist_dir 执行 publish_cmd（npm publish）；
  • 记录发布元数据到 release_info/<component>.txt，格式 REPO|COMP|KEY|VER。

3. 自动回写与 PR（update-workflow）

位置与逻辑：coco-app-web.yml

  • 下载并遍历所有 release-info；
  • 用 sed 回写工作流 inputs 的默认版本；
  • 用 jq 回写 components.json 的 current_version；
  • 生成并自动合并 PR，确保“配置=事实”。

4. 失败通知（notify_on_failure）

位置：coco-app-web.yml

  • 通过飞书机器人推送失败状态与链接。

如何新增组件

以新增 ui-common 下的 ai-answer 为例：

npm 仓库配置 OIDC

先第一次手动发布，在 npm 生成对应组件库的地址，然后修改一下配置，如图：

image.png

在 components.json 添加组件条目（路径、版本与目录）

{
  "ui-common": {
    "components": {
      "ai-answer": {
        "current_version": "0.0.1",
        "work_dir": "packages/AIAnswer",
        "dist_dir": "packages/AIAnswer"
      }
    }
  }
}

在工作流 inputs 增加对应键（命名约定）

AI_ANSWER_VERSION: { description: 'ai-answer Version', required: true, default: "0.0.1" }

image.png

校验与发布：

  • 手动触发 workflow_dispatch，传入一个“不同于 current_version”的版本号（如 0.0.2）；
  • 观察日志出现 Processing: ai-answer (ui-common)；
  • 发布完成后自动生成并合并 PR，回写工作流默认值与 components.json 的 current_version。

好处与设计取舍

  • 统一入口：一个工作流覆盖多仓库多组件的发布。
  • 精准触发：仅版本变化的组件进入矩阵，节省时间与算力。
  • 自动同步：发布后自动回写配置与默认值，杜绝版本 “事实与配置” 不一致。
  • 配置集中：components.json 管理构建/发布命令与目录，组件可覆盖仓库默认，保持最少差异。
  • 高扩展：新增组件只需改两处配置，无需动工作流逻辑。

设计要点：

  • 键名映射（SAFE_NAME + _VERSION）保证 inputs 与组件名稳定对应；
  • jq 层级读取（组件优先、仓库兜底）降低重复配置；
  • release-info 作为 “事实记录”，update-workflow 根据事实回写配置，实现幂等与自愈。

常见坑位与排查

  • 键名不匹配
    • ai-answer 的键必须为 AI_ANSWER_VERSION；漏下划线或命名不一致会导致 INPUT_VER 为 null。
  • 目录错误
    • work_dir 用于构建，dist_dir 用于发布；两者必须存在且正确。
  • 版本写法不匹配
    • tsup.config.ts 必须存在形如 version: "x.y.z" 的明确字段；否则请改用 package.json。
  • 私有仓库
    • repo_private 为 true 时需配置 SSH 私钥，checkout 才能访问。
  • npm 凭据
    • 确保目标仓库/流水线具备 npm 发布权限（token 或 OIDC）。
  • 组织变量
    • vars.GIT_REPO 必须指向组织路径（如 github.com/<org>），否则 checkout 失败。
  • 适配脚本
    • adapter_script 仅在特殊仓库需要（如 coco-app），默认关闭避免误改。

小结

  • 这套流水线以 “版本变化” 为核心驱动力，结合集中配置、自动回写与 PR，构建出稳健、可扩展的多组件发布通道。
  • 新增组件的心智负担被压缩为 “加配置 + 加输入键”，其余交给 CI 自动完成。
  • 对于多个组件分布在多仓库的场景，这是一个低成本、高收益的发布实践。
❌
❌