企业官网建设流程全解析

• 测试

导读

CHANGELOG.md 是 axe-core 项目最权威的版本编年史，完整记录了从 v1.0.1（2015 年首次公开发布）到 v4.13.0（2026 年）十余年间的功能新增、Bug 修复与破坏性变更。本文以该变更记录为主体骨架，结合仓库内的 lib/ 源码、lib/rules/ 规则定义、locales/ 语言包与 package.json 构建配置，帮你读懂 axe-core 的版本节奏、重大架构转折（如 4.x 的规则影响一致性治理、ElementInternals 支持），并掌握如何从版本号与提交信息中快速定位影响自身集成的变更点。

一、变更记录的组织方式：conventional commits 与 commit-and-tag-version

CHANGELOG 开头即声明本项目遵循 commit-and-tag-version 的提交规范。这意味着每条变更条目都来自符合 Conventional Commits 规范的提交信息，并按语义化版本（SemVer）自动归类：

• Features：新增能力（新规则、新 API、新语言包等），对应 minor 版本；
• Bug Fixes：缺陷修复，对应 patch 版本；
• BREAKING CHANGES：破坏性变更，对应 major 版本；
• 另有三类从源码结构可见的常规分类：Deprecations（弃用预告）、Performance Improvements（性能优化）与Type Fixes & Improvements（类型定义改进）。

这一约定也体现在 package.json 的commit-and-tag-version配置中：postbump钩子会先执行pnpm ci构建，再运行sri-update刷新 SRI 哈希并更新 doc/rule-descriptions.md；同时skip.tag为true，说明打 tag 由发布脚本（pnpm run release）另行控制。仓库根目录的 sri-history.json 正是历次构建产物 SHA-256 哈希的存档（自 4.5.0 起官方弃用该文件，但保留兼容），配合package.json中的sri-update/sri-validate脚本可校验 CDN 上axe.min.js的完整性。

给集成方的提示：阅读 CHANGELOG 时，一条条目末尾的括号内通常带有closes #issue、references #issue等元信息。例如 4.13.0 中 "aria-actions" 条目同时引用了 #4584、#5199、#5215 等多个 issue，这表示该改动涉及多个相关讨论，需要一并查阅才能理解完整上下文。

二、版本节奏总览：从 1.x 到 4.x 的里程碑

通读全部 2083 行变更记录，可以梳理出如下主线：

当前仓库锁定版本为4.13.0（见 package.json 的version字段），因此下文重点解读 4.x 主线，特别是 4.8.0 与 4.12–4.13 两个里程碑。

三、v4.0.0：一次彻底的"瘦身"——破坏性变更清单

4.0.0 是 axe-core 4.x 时代的起点，其 Breaking Changes 部分列出从 3.x 继承并在 4.0 中正式移除的资产：

被移除的规则（rules）：

• aria-dpub-role-fallback（DPUB 角色回退）
• checkboxgroup
• layout-table
• radiogroup
• video-description

被移除的检查（checks）：

• aria/implicit-role-fallback
• forms/fieldset
• forms/group-labelledby
• media/description
• tables/has-caption
• tables/has-summary
• tables/has-th

从当前仓库目录看，lib/rules/ 中已不存在上述规则文件，而新增的 layout-table-matches.js 则作为匹配器保留，印证了"规则删除、匹配逻辑另行拆分"的演进路径。同时 4.0.0 引入并构建了standards 对象（lib/standards/ 下的aria-roles.js、aria-attrs.js、html-elms.js、dpub-roles.js、graphics-roles.js），把 ARIA/WAI-ARIA/HTML 语义数据从散落的 commons 函数中集中为一份可编程的标准表，此后的角色、属性、元素语义检查全部基于该数据源驱动——这是 4.x 架构最根本的变化之一。

四、v4.8.0：Consistent Rule Impact——让规则影响级别"一成不变"

4.8.0 在 CHANGELOG 中拥有独立的专题小节（"Consistent Rule Impact"），是理解 axe-core 结果模型的关键版本：

该版本让一条规则永远不再动态改变其报告的 impact（影响级别）。为了在不改变既有问题严重程度的前提下实现这一点，部分规则被拆分成多条。

具体拆分与调整如下：

• 弃用检查上的 impact 字段，改为由规则统一定义（#4114）：在 axe-core 4.8 之前，impact 可以在 check 层面配置；此后 impact 只归属 rule，保证同一条规则在不同命中场景下结果一致。
• 新增规则aria-deprecated-role（#4074）与aria-conditional-attr（#4094），用于承接原属其他规则的"需要人工复核"类结果。
• 固定 impact 为 serious：aria-input-field-name、aria-toggle-field-name（#4095）。
• 固定 impact 为 critical：aria-roles、aria-valid-attr-value（#4112）。
• 固定 impact 为 moderate：scope-attr-valid（#4113）。
• 新规则aria-prohibited-attr（#4088）与aria-braille-equivalent（#4107）加入规则集。

这一治理的直接后果是：迁移 4.7 → 4.8 时，部分问题的 impact 可能从之前的动态值变成固定值。对 CI 集成方而言，若以 impact 作为阻断阈值（例如"serious 以上才失败"），升级后需要重新校验自己的阈值配置。同时 4.8.0 还弃用并默认关闭了duplicate-id/duplicate-id-active（#4071），duplicate-id-aria改为"失败时进入 needs review"并打上wcag412标签。

Type 层面的连带变更（4.8.0 的 "Type Fixes & Improvements"）：target与ancestry两个属性的返回类型由string[]修正为UnlabelledFrameSelector——因为在包含 Shadow DOM 的选择器场景下，string[]并不正确。任何硬编码把这两个字段当作string[]消费的调用方都需要调整。对应的类型定义文件为仓库根目录的 axe.d.ts。

五、v4.12 – v4.13：ARIA 1.2 与 ElementInternals 的深度支持

4.12.0 与 4.13.0 是 4.x 后期最重要的能力扩展，核心关键词是ElementInternals（自定义元素通过attachInternals()暴露 ARIA 状态的新标准机制）：

4.12.0（2026-06）新增：

• gather-internals.js外部脚本（#5099），用于在自定义元素尚未定义时也能采集 ElementInternals 数据；
• axe.externalAPIs提供设置 elementInternals 数据的公开 API（#5105），对应源码 lib/core/public/external-apis.js；
• 公开axe.normalizeRunOptions（#4998），便于在外部复现 run 参数的标准化逻辑（lib/core/public/run/normalize-run-params.js）；
• 新增axe.resetLocale()（#5108）恢复默认语言，源码见 lib/core/public/reset-locale.js；
• axe.getRules()返回对象新增enabled字段（#5118）——当前实现（lib/core/public/get-rules.js）会结合规则自身的enabled与审计的tagExclude计算真实启用状态；
• aria-required-attr与aria-required-parent/children等规则部分支持 internals role（#5080）；
• 新增utils.getElementInternals工具函数（#5077）。

4.13.0（2026-08）新增：

• ElementInternals 默认启用（#5284），无需再通过配置开关开启；
• ARIA 标准表新增aria-actions属性（#5200），当前 lib/standards/aria-attrs.js 中可看到其定义为idrefs类型、allowEmpty: true、global: true，并映射到ariaActionsElements属性；
• aria-allowed-attr将废弃 ARIA 属性标记为 needs-review（#5246）；
• 新增sectionheader/sectionfooter角色（#5238）；
• 新增aria/getAriaValue（#5109）与aria/hasAriaValue（#5136）两个 commons 函数；lib/commons/aria/get-aria-value.js 的实现按attribute → property → internals三级顺序取值，并且只有当attrStandard.caseInsensitive为真时才做小写归一化——这正对应 4.13.0 中"standards/ariaAttrs增加caseInsensitive属性"（#5224）的条目；
• 新增dom/getResolvedRefs（#5151）解析 idrefs 指向的虚拟节点；
• role=image与role=img等价（#5248），并顺带更新了role-img-alt/svg-img-alt的元数据命名（#5279）；
• 新增inSectioningContent、hasChild、isSummaryForDetails三个 matches 匹配器（#5262）。

源码印证：在 lib/ 目录中检索ElementInternals，命中 lib/commons/aria/get-aria-value.js、lib/commons/text/label-text.js、lib/core/base/virtual-node/virtual-node.js 与 lib/core/public/external-apis.js 等十余个文件，说明 internals 支持已贯穿"虚拟节点构建 → 文本计算 → ARIA 取值 → 公开 API"整条链路，而非个别规则的特判。

迁移注意：由于 ElementInternals 从 4.13 起默认开启，如果你在自定义元素上通过 internals 暴露了 ARIA 语义，升级后这些语义会自动进入检测范围；这通常带来更准确的检测结果，但也可能让此前"看不见"的违规突然出现，建议升级后在自定义组件页面上做一次全量回归。

六、新规则时间线：从 WCAG 2.0 到 WCAG 2.2 的规则演进

CHANGELOG 中 "new-rule" 条目清晰勾勒出规则集的扩张脉络：

以 4.5.0 的target-size为例，当前规则定义见 lib/rules/target-size.json：impact: serious、enabled: false（默认关闭）、匹配器为widget-not-inline-matches，由target-size与target-offset两个检查联合判定，标签wcag22aa/wcag258/EN-9.2.5.8。4.8–4.11 的多条修复（如 #4376 "always pass 10x targets"、#5000/#5066 对 inline 与 offscreen 元素的豁免、#5012 对display:inline目标的 clientRects 计算）说明这条规则的几何计算在持续打磨。

七、i18n 演进：从单语言到 20+ 语言包

CHANGELOG 中 i18n 类条目贯穿始终：3.1 引入运行时本地化支持，此后各版本陆续加入日语、法语、西班牙语、葡萄牙语（pt_BR/pt_PT）、德语、巴斯克语、希腊语、意大利语、简体/繁体中文、希伯来语、挪威语、波兰语、俄语、瑞典语等。当前仓库的 locales/ 目录共存 19 个语言文件与 locales/_template.json 模板，4.12.0 还修复了 locale 子标签设置（#5112）并新增axe.resetLocale()，配合package.json中translate/--all-lang构建脚本，可产出单语言或多语言版本的axe.min.js。

对产品团队而言，这意味着无障碍报告的提示文案可以随产品语言本地化；同时 CHANGELOG 中大量 "locale: proofread/typos" 类修复提示：语言包属于持续维护资产，升级时建议顺带同步更新。

八、API 与类型系统演进：集成方最关心的兼容面

• 运行 API：2.1.7 引入 Promise 化的axe.run()替代axe.a11yCheck()；3.4 起axe.run可接受字符串形式的runOnly（4.3.0 强化）；4.0 起options.ancestry可为节点附加 CSS 选择器；4.3 增加axe.runPartial()与getFrameContexts()（lib/core/public/run-partial.js），支撑"无 iframe 通信的测试"场景。
• 配置与消息：4.4.0 将branding由对象改为字符串；4.2 引入axe.frameMessenger与allowedOrigins（lib/core/public/frame-messenger.js），并新增pingWaitTime配置调节 iframe 探测超时。
• 类型定义：根目录 axe.d.ts 与 typings/axe-core/axe-core-tests.ts 是类型层演进的载体；CHANGELOG 中 4.3 的PartialResults、4.4 的NodeList上下文、4.7 的setup/teardown与 reporter 定义、4.8 的UnlabelledFrameSelector、4.11 的nodeSerializer类型、4.12 的RuleMetadata.enabled可选化（#5129）都直接影响 TypeScript 用户的编译通过率。

九、性能优化史：大型站点的检测成本控制

自动检测引擎的实用门槛是性能，CHANGELOG 中的 Performance 条目可作为调优参考：

• 选择器层：4.5.0 "greatly improve the speed of querySelectorAll"（#3423）、3.0-beta "normalize all selectors for better cache utilization"；
• 颜色对比：3.5.0 "greatly improve performance for very large sites"（#1943）、4.0 基于elementsFromPoint的重构、4.1 "greatly improve color-contrast-matches speed"；
• 规则调度：3.2.0 "Defer rules rather than checks"（#1308）、performanceTimer指标（3.3 起为规则增加计时，4.11 修复其在 iframe 中的表现 #4834）；
• 布局网格：4.8.0createGrid只把可见的非溢出区域加入网格（#4101），4.5.2 又修正了滚动出视野元素的网格收录（#3773）。

仓库 perf/ 目录存放了 v4.11.0 至 v4.13.0 的报告 JSON 与对比脚本（perf/compare.js、perf/report.js），package.json提供perf:report脚本，可复现各版本在 perf/sites/ 样本页（如 MDN 页与超长页面）上的耗时对比。

十、如何把 CHANGELOG 变成你的升级手册

综合上述分析，建议在升级 axe-core 时按以下顺序使用 CHANGELOG：

1. 先扫 Breaking Changes / Deprecations 小节：确认目标版本与前序版本之间是否有移除的规则、检查或 API（如 4.0.0 的移除清单），对照你自己的axe.configure({ rules: ... })配置是否引用了已消失的 ID；
2. 再读该版本的 Features 与 Fixes：重点查看你依赖的规则 ID（如color-contrast、target-size、aria-*）是否出现，并结合 lib/rules/ 下同名.json文件的enabled、impact、tags字段判断默认行为变化；
3. 核对类型定义：若项目使用 TypeScript，检查axe.d.ts变更是否波及RunOptions、NodeResult等类型；
4. 关注 i18n 与 sri：语言包更新可通过 locales/ 核对；sri-history.json与pnpm run sri-validate可校验 CDN 产物哈希；
5. 用 ACT/集成测试兜底：仓库的 test/act-rules/（W3C ACT 规则对照测试）、test/integration/（浏览器端到端）与 test/aria-practices/（APG 模式测试）在升级后全量跑一遍，是最可靠的回归手段。

一句话总结：axe-core 的 CHANGELOG 不只记录"改了什么"，更记录了它如何从单一页面检测库演化为覆盖 WCAG 2.0/2.1/2.2、ARIA 1.2、ElementInternals、多语言与 iframe/Shadow DOM 复杂场景的可编程无障碍检测平台；读懂版本间的语义变化，是安全升级、准确配置规则集的前提。

• 测试