企业官网建设流程全解析

• AI 应用
• 大模型
• RAG
• 语音
• 后端
• 前端
• 桌面应用

本篇是 BiliNote 开源仓库的发版执行手册（Release Manager 视角），完整覆盖从develop分支切出发布分支、编写 CHANGELOG、双 PR 合并与回灌、打 tag 触发 CI 自动构建插件产物，到人工上传 Chrome Web Store / Edge Add-ons / Firefox AMO 以及桌面端（Tauri）发布的每一步。读完你不仅能按步复现一次完整发版，还能理解release-extension.yml、commitlint 等仓库基础设施如何在底层约束和自动化这条发布链路。

发版全景：一条主线，三类交付物

BiliNote 采用简化 Git Flow（详见 CONTRIBUTING.md），发版主线固定在develop → release/X.Y.Z → master → tag这条路径上。RELEASING.md 给出的完整流程如下：

develop ──→ release/X.Y.Z ──→ PR ─→ master ──→ 打 tag vX.Y.Z │ │ │ └──→ PR 回灌 ──→ develop └──→ CI 自动构建插件产物 + 挂到 GitHub Release ↓ 人工上传商店（Chrome/Edge/Firefox）

一次发版最终产出三类交付物：浏览器插件（由 push tag 触发的 CI 构建出.zip/.xpi/.crx并挂到对应 GitHub Release）、桌面端安装包（Tauri 构建，同样由v*tag 触发），以及人工提交商店审核（Chrome / Edge / Firefox 三商店，审核周期普遍 1-3 个工作日）。

第一步：从 develop 切发布分支

在本地终端执行：

git checkout develop && git pull origin develop git checkout -b release/X.Y.Z

版本号遵循SemVer 语义化版本规范：MAJOR.MINOR.PATCH。与之对应的分支命名规范在 CONTRIBUTING.md 中有明确约定：release/<版本号>必须与实际 tag 一致（如release/2.1.0↔v2.1.0），全小写、用中划线连接。

仓库的简化 Git Flow 中，release/*是短生命周期分支（创建来源develop，合并去向master+develop，合并后删除），它的定位是版本冻结、回归、发版准备——冻结期内不允许再合入新需求，只允许修复发布缺陷。

第二步：写 CHANGELOG、更新版本号

在release/X.Y.Z分支上完成三处文档更新：

1. 编辑 CHANGELOG.md：在文件头部新增## [X.Y.Z] - YYYY-MM-DD段。仓库明确采用 Keep a Changelog 分类体系：Added / Changed / Fixed / Removed / Security / Internal。实际仓库中的写法可参考 CHANGELOG.md，例如## [2.4.4] - 2026-06-23下挂### Security，[2.4.3]下挂### Fixed，每条变更都带 issue 编号与具体说明。
2. 编辑 README.md 顶部标题中的版本号，并新增「vX.Y.Z 新增」摘要段（与 CHANGELOG 中该版本新增内容对应，仓库历史如### v2.3.0 新增段即是此类摘要）。
3. 重大变更同步更新 CLAUDE.md（仓库结构 + 各 workspace 开发命令说明，涉及工作区级重大调整时更新）。

随后提交并推送：

git commit -am "docs: vX.Y.Z CHANGELOG + README 版本" git push -u origin release/X.Y.Z

第三步：合并 master + 回灌 develop（双 PR）

在 GitHub 上发起两个 PR，两者合并方式都必须使用 Merge commit（--no-ff）：

为什么合并标题必须符合 commitlint

⚠️ Merge commit 的标题必须符合type(scope): subject格式——仓库的 commitlint 会在 push 到master/develop时校验。历史上用过Release vX.Y.Z这种形式，会被 commitlint 报type-empty/subject-empty。

这一点有完整的仓库实现支撑：根目录的 .commitlintrc.json 基于@commitlint/config-conventional，把type-enum白名单限定为feat / fix / docs / style / refactor / perf / test / build / ci / chore / ui / revert十二种；.github/workflows/commitlint.yml 在develop/master的 push 以及所有 PR 上运行 commitlint，fetch-depth: 0以便检查全部提交历史。这也是为什么发版 merge commit 标题统一写成chore(release): ...——chore是合法 type，(release)是 scope，vX.Y.Z是 subject。

分支保护与回灌的意义

• master分支保护要求review 通过才能合并。
• 回灌develop是为了把发版冻结期内的小修同步回开发主干，避免修复丢失。CONTRIBUTING.md 中强调：release/*合入master与回灌develop均使用 Merge commit，保留发版结构；而日常feature/*/fix/*合入develop推荐 Squash and merge 以保持历史线性。

第四步：打 tag，触发 CI 自动构建

git checkout master && git pull origin master git tag -a vX.Y.Z -m "BiliNote vX.Y.Z 主线： - ... 详见 CHANGELOG.md" git push origin vX.Y.Z

push tag会自动触发 .github/workflows/release-extension.yml：构建插件并把.zip/.xpi/.crx挂到对应 GitHub Release。

CI 构建链路做了什么

对照工作流源码，触发与构建细节如下：

• 触发条件：on.push.tags匹配'v*'，即任何v开头的 tag（release-extension.yml）；
• 构建环境：ubuntu-latest，pnpm固定 9 系、Node 20（cache-dependency-path指向BillNote_extension/pnpm-lock.yaml）——这两个版本钉死与仓库历史中「pnpm 11 不兼容 Node 20」等构建事故的修复直接相关（见 README.md 的 v2.2.1 / v2.2.2 修订记录）；
• 构建命令：pnpm install --frozen-lockfile→pnpm build，对应 BillNote_extension/package.json 中的build脚本（生产模式依次执行 clear / build:web / build:prepare / build:background / build:js）；
• 产物打包：pnpm pack:zip（jszip 打包extension/为extension.zip，Chrome / Edge 上传格式）、pnpm pack:xpi（web-ext 构建 Firefox 扩展）、pnpm pack:crx（自托管 sideload 用）；
• crx 的稳定性说明：crx 需要稳定key.pem才能保持插件 ID 不变。CI 中没有该密钥时用continue-on-error: true跳过、不阻塞主流程；若想生成稳定 crx，需把 key 存入 secretEXTENSION_CRX_KEY并解开工作流中的注释（release-extension.yml）；
• 命名与挂载：把extension.zip/.xpi/.crx重命名为bilinote-extension-${VERSION}.zip等带版本后缀的产物，再由softprops/action-gh-release@v2挂到对应 Release（fail_on_unmatched_files: false，缺某类产物不报错）。

桌面端同样由v*tag 触发（.github/workflows/main.yml），构建时从 tag 注入版本号到tauri.conf.json（github.ref_name去掉前缀v，如v2.3.2→2.3.2），确保产物版本与 Release 版本对齐——这一步对应 CHANGELOG 中「桌面端构建产物版本恒为 2.0.0」的修复（CHANGELOG.md）。

第五步：创建 GitHub Release（如还没有）

CI 默认会创建 / 更新vX.Y.Z对应的 Release。如果你想自己撰写 release notes：

1. 打开 GitHub 仓库的 Releases → New 页面；
2. Tag 选择vX.Y.Z；
3. Title 填vX.Y.Z；
4. Body 直接粘贴 CHANGELOG.md 中对应版本的段落；
5. CI 跑完后，Release 页面会自动出现bilinote-extension-X.Y.Z.zip/.xpi/.crx产物。

第六步：人工上传各商店

商店审核普遍 1-3 个工作日。建议顺序：先 Chrome → Edge → Firefox（Edge 接受与 Chrome 同一份 zip）。

Chrome Web Store

1. 进入 Chrome Web Store 开发者控制台；
2. 选 BiliNote → 左侧Package→Upload new package；
3. 上传bilinote-extension-X.Y.Z.zip；
4. 检查 listing（描述 / 图标 / 截图无变化可保持），点Submit for review。

Microsoft Edge Add-ons

1. 进入 Microsoft Partner Center 的 Edge 插件仪表盘；
2. 选 BiliNote →New submission；
3. 上传同一份.zip（Edge Add-ons 与 Chrome 完全兼容 MV3）；
4. 提交审核。

Firefox Add-ons (AMO)

1. 进入 addons.mozilla.org 的开发者后台；
2. 选 BiliNote →Upload New Version；
3. 上传bilinote-extension-X.Y.Z.xpi；
4. 选择「在 AMO 公开」或「自托管」；
5. 提交审核。

桌面端 (Tauri)

仓库已有 GitHub Actions 在v*tag 时构建桌面端安装包并自动挂到 GitHub Release，无需额外操作。main.yml会收集.dmg/.msi/ NSIS.exe安装包并上传（main.yml）。

第七步：清理 release 分支

# release 分支已合到 master 与 develop，删掉 git push origin --delete release/X.Y.Z git branch -d release/X.Y.Z

这符合 CONTRIBUTING.md 的合并规范：短期分支合并完成后必须删除（远端 + 本地），已完成的分支不得继续承接新需求。

可选：配置 secrets 实现商店自动发布

.github/workflows/release-extension.yml 末尾有三段商店自动发布的 job 注释（publish-chrome/publish-edge/publish-firefox），默认禁用。要启用：

1. 在 GitHub 仓库 Settings → Secrets and variables → Actions 中添加对应 secrets：

2. 解开工作流文件末尾publish-chrome/publish-edge/publish-firefox三个 job 的注释；
3. 之后 push tag 时即自动发布到商店。

工作流注释中还给出了各商店 secret 的获取方式指引：Chrome 参照 chrome-webstore-upload-cli 的 Google API key 生成说明（需CHROME_CLIENT_ID/CHROME_CLIENT_SECRET/CHROME_REFRESH_TOKEN对应 OAuth 客户端与刷新令牌）；Edge 使用 Edge Add-ons API（EDGE_PRODUCT_ID即插件 product ID，EDGE_CLIENT_ID/EDGE_API_KEY为 Azure 应用凭证）；Firefox 在 AMO 开发者后台的 API Key 页面生成。三个 job 分别基于mnao305/chrome-extension-upload、wdzeng/edge-addon、trmcnvn/firefox-addon三个 GitHub Action 实现，产物路径均指向带版本号的bilinote-extension-${github.ref_name}.zip/.xpi。

紧急 hotfix 发版：不走 release/，走 hotfix/

线上紧急问题不经过release/*分支：

git checkout master && git pull git checkout -b hotfix/<scope>-<事项> # … 修复 ... # PR base=master 合入；同时 PR base=develop 回灌

合入master后通常打patch tag（如v2.1.1），CI 流程与常规发版相同。CONTRIBUTING.md 对 hotfix 的约束包括：仅处理线上阻断性 / 高优先级缺陷；非紧急问题不得绕过develop直接走热修；若当前存在release/*即将发布，需评估是否同步到对应 release 分支，避免修复丢失。

历史发布快查

注：表格中的 Tag 指向 GitHub Releases 页面，可在仓库 Releases 板块查看对应版本的说明与产物。该表为发版手册中的历史记录，最新版本信息以 CHANGELOG.md 顶部与 README.md 标题版本号为准。

附：发版涉及的仓库文件速查

整套发版流程的本质，是用「简化 Git Flow 的分支纪律 + commitlint 的提交规范强制 + tag 触发的工作流自动化」把一次发布固化为可重复、可审计、可回滚的标准动作：文档与版本号先行，双 PR 保证主干与开发线同步，tag 一打，插件与桌面端产物自动就绪，剩下的只有三商店的人工审核环节。

• AI 应用
• 大模型
• RAG
• 语音
• 后端
• 前端
• 桌面应用