- 开发工具
- CLI
- 前端构建
【免费下载链接】extension-create
The cross-browser extension framework.
CHANGELOG.md 是 Extension.js 跨浏览器扩展框架仓库的版本史主线：它以## 版本号 (发布日期)为章节，记录从 3.8.0 到最新 4.1.33 的每个发布中的功能（Features）、修复（Fixes）与其余变更（Other changes）。本文以这份 Changelog 为主体，逐层解读其结构约定、近期版本的重大变化、各里程碑版本的能力升级，并深入仓库中的发布脚本与 CI 工作流，说明这些版本记录是如何被自动生成、校对、写回并对外签署验证的。
CHANGELOG.md 的结构与阅读约定
打开 CHANGELOG.md 可以看到固定的组织格式：
## Unreleased：文件最顶部是一个## Unreleased占位章节，发布流水线会把该章节替换为正式的版本章节（机制见下文 Changelog 如何被写入）。## <version> (<date>)：每个版本一个二级标题，日期采用en-US长格式（如## 4.1.33 (October 8, 2026)，见 CHANGELOG.md#L5）。- 加粗 Highlights：重要版本在章节开头用加粗条目突出"用户现在能做什么"，例如 4.1.33 的 Safari 开发会话行为调整与 sidebar 模板增强（CHANGELOG.md#L7-L8）。
### Features/### Fixes：用户可见的新增能力与修复，每条带 PR 号与 commit 短哈希链接。<details>折叠的 Other changes：数量较多、面向实现者的变更（测试、CI、依赖升级、文案等）统一折叠在Other changes (N)中，保持正文可读。- No changes listed.：空发布（如 4.0.29，见 CHANGELOG.md#L945）会显式标注，而不是留一个空章节。
值得注意的是版本风格演变：早期版本（4.0.9 及以前）使用带 emoji 的小节标题（### 🚀 Features、### 🐛 Fixes、### 🧹 Other changes），从 4.0.10 起 Changelog 记录了 "Strip emojis from generated release notes"（CHANGELOG.md#L1436），随后生成器统一了无 emoji 的### Features/### Fixes/Other changes格式——这正是 4.1.x 各版本呈现的样式。
最新版本 4.1.33 与 4.1.x 近况
当前仓库中四个公共包（extension、extension-develop、extension-create、extension-install）的版本号均为4.1.33，与 Changelog 顶部条目一一对应，例如 programs/extension/package.json 中的"version": "4.1.33"与engines.node: ">=22.12"。4.1.33 的两个发布亮点（CHANGELOG.md#L5-L9）：
- Safari dev runs leave your Safari alone：一次
extension dev打开的 Safari 实例保持在后台，停止时只退出该实例，不触碰用户自己的 Safari。 - Sidebar starters read the page：所有
extension create的 sidebar 模板内置了一条现成的消息通道，用于向打开的标签页请求其标题，面板跟随页面的场景从可用代码起步。
4.1.x 系列对使用者影响最大的几个版本：
| 版本 | 关键变化（摘自 Changelog 原文） |
|---|---|
| 4.1.33（2026-10-08） | Safari dev 会话隔离退出；sidebar 模板内置取页面标题的消息通道 |
| 4.1.31（2026-10-04） | side_panel/sidebar_action/action按浏览器翻译（一个侧栏/工具栏键位构建全部浏览器）；zip 产物移到dist/<name>-<version>-<browser>.zip（CHANGELOG.md#L80-L83）；dev server 对未知 host 返回 403 并提示--allowed-hosts |
| 4.1.26（2026-09-20） | --browser=zen/--browser=floorp按名启动；--minify/--no-minify覆盖任意目标的压缩默认值（CHANGELOG.md#L272-L273） |
| 4.1.25（2026-09-18） | content script 保存后精确运行一份拷贝，旧拷贝不再并存 |
| 4.1.24（2026-09-18） | 固定@rspack/core到 2.2.3，修复 4.1.18–4.1.23 带样式表页面加载报错；新增transformers-js侧栏模板 |
| 4.1.21（2026-09-17） | Bun 1.2+ 可作为 CLI 运行时（bunx --bun extension@latest dev）；运行时加载的模块通过import.meta.url读到自身产物路径（CHANGELOG.md#L357-L359）；manifest_version全被 vendor 前缀限定时的构建现在会被拒绝并给出修法 |
| 4.1.20（2026-09-16） | Deno 2.5+ 可作为 CLI 运行时（deno run -A npm:extension@latest）（CHANGELOG.md#L415） |
| 4.1.1（2026-08-20） | v4 起要求 Node.js 22+，Node 20 不再支持且无 API 变化；多文件 content script 热更新；Safari dev 后台 resync；dev 会话退出时可靠关闭浏览器（CHANGELOG.md#L1632-L1635） |
升级项目时的实用结论：如果你依赖--minify、Safari 开发流程或 zip 产物路径，4.1.31 的 zip 路径迁移（dist/<browser>/内 →dist/旁边）和 4.1.26 的 minify 开关是最需要核对的两处；运行时层面 Bun（4.1.21 起）与 Deno（4.1.20 起）都受 CI 冒烟覆盖，但 Node 仍是基准运行时（engines.node >= 22.12）。
里程碑版本速览：框架能力是如何长成今天的样子的
Changelog 后半部分记录了框架能力的关键节点：
- 3.18.0（2026-05-28）：一次能力大版本，引入
extension publish（通过可分享 URL 分发构建）、extension logs（读取与流式订阅控制通道日志）、agent bridge 的act/inspect切片与 consumer client、默认模板打包，以及 Safari（alpha）目标支持与 Chromium/Firefox runner 加固（CHANGELOG.md#L1729-L1732）。 - 3.15.0（2026-05-04）：加入面向扩展负载的按类别性能预算（per-category perf budgets），随后 3.18.0 将其默认值提升到 512/512/1024 KiB。
- 4.1.19（2026-09-15）：
chrome:/edge:manifest 前缀变为 vendor 精确匹配，这是 4.1.21 中"没有manifest_version的构建被拒绝"问题的前置背景。 - 4.0.3（2026-07-01）：支持通过 engine-family manifest 键命名浏览器分叉（engine-family manifest keys），此后 Waterfox、LibreWolf、Brave、Opera、Vivaldi、Yandex、Zen、Floorp 才逐步成为按名启动的一等目标。
- 3.8.0（最末条目）：最早记录的能力包括 canary 发布通道与实验性的
install命令（CHANGELOG.md#L2302-L2309），即今天的extension-install包前身。
这些条目共同说明 Changelog 不只是一份修复清单：浏览器目标面（Safari 从 3.18.0 的 alpha 到 4.1.33 的会话隔离）、运行时面（Node → Deno → Bun）、分发面（publish → zip → canary）的演进都可以通过它追溯。
发布说明如何被自动生成：generate-release-notes.mjs
Changelog 每条版本下的 Features/Fixes/Other changes 分组并非手写，而是由 scripts/generate-release-notes.mjs 从 git 历史生成（docs/RELEASING.md 明确了 "Release notes are generated from git history usingscripts/generate-release-notes.mjs"）。脚本核心机制与 Changelog 的形态一一对应：
- 确定 commit 区间：
resolveRange()用上一版本对应的 release 提交作为锚点，得到anchor..toRef区间，--no-merges收集提交。 - 过滤发布机制自身：
RELEASE_MACHINERY_GREP匹配release(stable|next|canary)、chore(release): move changelog to v*等提交，保证"生成 Changelog 这件事本身"不会出现在 Changelog 里。 - 分类：
CATEGORIES按 subject 前缀做第一个命中归类——Features 命中Add、Support、Expose、Enable、Bundle、Surface、Enhance等动词；Fixes 命中Fix、Resolve、Patch、Stop、Harden、Prevent、Guard、Sweep等动词，以及to patch GHSA/to clear .*advisor这类安全修复措辞。这解释了为什么 Changelog 里大量修复条目前缀是 "Stop/Refuse/Keep/Make ..."：作者写 commit subject 时使用的动词决定了分组。 - 降噪：
IGNORED_PATTERNS排除 Dependabot 区间升级、Update pnpm-lock之类纯机械提交。 - 折叠 Other changes：未命中任何分类的提交全部进入
Other changes (N)折叠块——这正是每个版本章节尾部<details><summary>Other changes (7)</summary>的来源。 - Highlights 置顶：脚本读取 RELEASE_HIGHLIGHTS.md 的
## Highlights小节（1–3 条、以能力而非实现开头），置于版本说明最顶部；该文件模板注明"每次稳定发布后自动重置"。 - 多输出格式：同一份数据可渲染
markdown（GitHub Release / Changelog 正文）、discord（无 highlights 时取前 3 条 feature 领衔并附N features · N fixes · N other统计）、tweet（180 字截断）与json。
生成逻辑有对应的回归测试 scripts/spec/generate-release-notes.spec.mjs，防止分类规则改动破坏已发布说明的格式。
Changelog 如何被写入：move-changelog.mjs
scripts/move-changelog.mjs 负责把 CHANGELOG.md 顶部的## Unreleased章节"落位"为正式版本章节，其逻辑可以直接对上文件形态：
- 若文件没有
## Unreleased则先补一个，保证幂等； - 将区间内容替换为
## Unreleased\n\n## <version> (<date>)\n\n<release notes>\n\n，release notes 即上面生成器产出的正文，缺省为- No changes listed.（对应 4.0.29 的写法）； - 日期由
formatReleaseDate()用Intl.DateTimeFormat('en-US', {month: 'long', day: 'numeric', year: 'numeric', timeZone: 'UTC'})生成——这就是## 4.1.33 (October 8, 2026)这种日期格式的来源； - 失败即响亮：写入后若找不到
## <version> (标题则直接抛错，注释写明这是为了防止"Changelog 没有版本标题"再次被无声发布。
该脚本的行为由 scripts/spec/move-changelog.spec.mjs 锁定，配合根目录 package.json 的move-changelog.mjs调用与发布流水线，构成"生成 → 写入 → 校验"的闭环。
发布通道、包范围与签名验证
Changelog 里的每个版本号背后是一套固定流程，docs/RELEASING.md 给出了权威描述：
- 三个通道：
stable（npm dist-taglatest）、next（next，必须使用 pre-release semver）、canary（canary，静默通道，可由流水线自动生成<base>-canary.<run_number>.<short_sha>版本号，且刻意跳过 git tag、GitHub Release、Changelog 更新与 Deployment——这解释了 Changelog 里为什么只有稳定与 next 版本）。 - 包范围：只有
programs/extension→extension、programs/create→extension-create、programs/develop→extension-develop、programs/install→extension-install四个公共包随版本发布（与 pnpm-workspace.yaml 的 workspace 布局一致），因此 Changelog 的版本号同时推进四个包的package.json。 - 模板钉版：stable/next 发布前 CI 会把
extension create的模板钉版移到extension-js/examples的 main 头部（node scripts/generate-template-corpus.mjs --ref main），并对内置javascript模板跑漂移检查——Changelog 中反复出现的 "Repin the template catalog ..."、"Resync the bundled javascript template ..." 条目，正是这一机制的落痕（如 CHANGELOG.md#L327）。 - 触发与产物：
Release – Publish工作流（.github/workflows/publish-release.yml）以workflow_dispatch输入channel+version，CI 校验、构建、测试后通过 npm trusted publishing（OIDC，id-token: write+--provenance，不读 npm token）发布。 - 可验证性：每个版本可用 docs/VERIFYING_RELEASES.md 描述的方式核验——npm 包带 provenance（
npm audit signatures、npm view extension@4.1.18 dist.attestations），GitHub Release 附带四个包 tarball 与 SLSA provenance 文件，签名采用 Sigstore 无密钥模式，由 release-attest.yml 工作流完成。
此外还有一个"发布后清洁"环节：scripts/clean-release-notes.mjs（由 clean-release-notes.yml 驱动）会扫描 GitHub Release 正文，剔除chore(release):、release(...):、Release stable v*、Move the changelog to v*等发布机制条目——与生成器侧的RELEASE_MACHINERY_GREP形成双保险，确保公开 Release 与 Changelog 都不含流水线自身的噪音提交。相关行为由 scripts/spec/push-release-refs.spec.mjs 等脚本测试约束。
如何使用这份 Changelog
- 升级前评估：按本文的 4.1.x 近况表 对照你的使用面（浏览器目标、minify、zip 路径、Safari 流程），再看目标版本章节的
Fixes是否命中你遇到的历史问题。 - 追溯某行为的引入点：Changelog 每条都带 commit 短哈希链接，可精确定位实现；对跨版本的演进（如 Safari、publish、性能预算），优先查 里程碑版本速览 所列版本。
- 参与贡献：若你给仓库提交功能或修复，commit subject 的动词前缀（Add/Fix/Stop/Support...）会决定它落在 Features 还是 Fixes；不希望出现在公开说明中的机械性提交会被
IGNORED_PATTERNS过滤；稳定版本的 Highlights 由维护者写入 RELEASE_HIGHLIGHTS.md。 - 核验发布：拿到任意发布版本后，按 docs/VERIFYING_RELEASES.md 的命令验证签名与 provenance，再对照 CHANGELOG.md 确认变更范围。
从 3.8.0 到 4.1.33，这份 Changelog 既是一份逐版本的能力演进档案，也是 Extension.js 发布工程（自动分类生成、Unreleased 落位、模板钉版、OIDC 签名、发布后清洁）的可见产物：读完它，你既能回答"这个版本改了什么"，也能回答"这些记录是怎么产生、为什么可信"。
- 开发工具
- CLI
- 前端构建
【免费下载链接】extension-create
The cross-browser extension framework.
相关推荐
Quivr 版本演进全解：从 CHANGELOG 读懂 RAG 平台的演化路线与自动化发布机制
Quivr 版本演进全解：从 CHANGELOG 读懂 RAG 平台的演化路线与自动化发布机制 本文以 Quivr 仓库根目录的 CHANGELOG.md ht
人工智能AI 应用大模型RAG后端前端REA 发布史解读：从 CHANGELOG 读懂 rea-agents 的 Conventional Commits 演进与版本治理
REA 发布史解读：从 CHANGELOG 读懂 rea agents 的 Conventional Commits 演进与版本治理 CHANGELOG.md
逆向工程MCP 服务AI 技能MinerU 版本演进全解：从 magic-pdf 重构到 hybrid 后端，读懂官方 Changelog 背后的技术决策
MinerU 版本演进全解：从 magic pdf 重构到 hybrid 后端，读懂官方 Changelog 背后的技术决策 本文以 MinerU 官方变更日志
人工智能大模型OCR计算机视觉
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
