技术文章

外部链接将在新标签页打开。

ACCESSIBILITY.md 被 GitHub 识别之后:无障碍声明该写目标、已知障碍,还是支持路径

一句话回答

GitHub 已将 ACCESSIBILITY.md 设为被识别的文件,并把声明内容拆成目标、已知障碍、支持的环境、贡献者预期与报告流程几块。对开发者来说,它们不是候选关系,而是一份声明的不同段落:支持路径与已知障碍先写,因为它们马上能用;目标后写,但写下去就要可被验收。没有测试依据时,写“未测试”比写“已支持”更稳妥。文件的具体展示位置与校验规则在现有材料中未说明,需要核实。

核心要点 TL;DR
  • 目标、已知障碍、支持路径是同一份声明的三个段落,不存在只写其中一个的版本。
  • 没有测试记录时,声明里写“未测试”比写“已支持”更经得起对照检查。

简短回答:不是三选一。GitHub 在 2026 年 11 月 5 日的博客摘要中提到,它现在会高亮仓库中的 ACCESSIBILITY.md,并帮助维护者记录无障碍目标、已知障碍、支持的环境、贡献者预期与报告流程(来源:GitHub Blog)。这五项是一份声明的不同段落,不是互斥选项。如果一定要排优先级:先写“支持路径”和“已知障碍”,因为读者拿到就能用;目标可以随后补,但一旦写下去,就得能被对照验收。

文件被识别之后,真正变化的是读者和性质#

同一个 Markdown 文件,放在仓库角落和出现在仓库页面上,面对的是两类人。前者多半是维护者自己的备忘,后者会被使用者、贡献者、采购评估方和无障碍审计人员读到。

性质也随之改变:从内部记录变成对外承诺。“我们支持屏幕阅读器”在备注里是描述,在声明里就是一个可以被逐条核对的句子。写之前先问一句:这句话如果被人拿实际环境来试,我能不能接受结果。

需要说明的是,本次材料只有博客摘要和一段作者介绍,没有正文规范。文件具体展示在仓库的哪个位置、是否校验内容格式、是否支持额外的元数据字段,这些都没有依据,待核实。

目标:写成可检验的句子#

  • 带范围:哪个产品面、哪些页面或组件,而不是“整个项目”。
  • 带状态:已做到 / 进行中 / 未开始。三级比一句“持续改进”有用得多。
  • 带验证方式:键盘走查、读屏软件试读、自动化扫描,各覆盖什么,说清楚。

建议避开没有审计支撑的合规表述,比如直接宣称完全符合 WCAG(Web Content Accessibility Guidelines,万维网内容无障碍指南)某个等级。标准本身没问题,问题在于这句话需要一个能被复查的依据;没有依据时,改写成“目标是在某时间窗内达到某等级,尚未完成评估”更站得住。

已知障碍:最容易漏,也最有用#

大多数声明只写成绩,不写问题。但对真正受影响的用户来说,知道障碍在哪、有没有绕行方案,价值高于一句“我们重视无障碍”。

每条障碍建议写四项:影响谁(哪类辅助技术使用者)、影响哪个操作、有没有临时替代路径、什么时候复查。数量上宁少勿假——三条真实的障碍,好过二十条“暂无已知问题”。

支持路径:写成能跑起来的流程#

这一块最容易被写成客套话。可执行的版本包含:

  1. 入口:issue 模板、专用邮箱或表单。地址请用真实可用的,示例中一律以 example.com 占位。
  2. 响应预期:给一个区间,比如“5 个工作日内首次确认”。不要写“尽快”。
  3. 需要对方提供什么:操作系统、浏览器与读屏软件版本、复现步骤。提前列出来,能省一轮往返。
  4. 替代获取方式:内容能不能以另一种格式拿到,这往往比修 bug 更快解决问题。

支持的环境与贡献者预期#

环境矩阵只在有测试记录时填。写了支持却没测过的组合,会在第一次被使用时暴露。区分“已验证”“未测试”“已知不支持”三态,比一张全部打勾的表更可信。

贡献者预期则是给提交者的检查清单:涉及交互组件的改动需要附什么说明、由谁复核、什么情况下可以豁免。这部分写得越具体,越不容易在评审时变成临时争论。

一个结构示例#

下面是用于说明分段的骨架,不是 GitHub 官方模板,字段名与格式不保证被识别,也未经过任何工具校验。示例中的邮箱为占位地址。

# 无障碍声明

## 目标
- 已做到:文档站正文页支持键盘导航(验证方式:键盘走查)
- 进行中:控制台表格支持读屏软件逐行朗读
- 未开始:图表组件的替代文本方案

## 已知障碍
| 位置 | 影响 | 临时方案 | 复查时间 |
| --- | --- | --- | --- |
| 控制台图表 | 读屏软件无法读取数据点 | 提供数据表下载 | 2027-02 |
| 移动端菜单 | 焦点顺序异常 | 暂无 | 待定 |

## 支持的环境
- 已验证:Chrome + NVDA(版本与日期待补)
- 未测试:Safari + VoiceOver、移动端读屏

## 贡献者预期
- 涉及交互组件的 PR 需附键盘走查说明
- 无法自查的部分在 PR 中标注,由维护者安排复核

## 报告问题
- 提交 issue 时请附:操作系统、浏览器与读屏软件版本、复现步骤
- 备用联系方式:access@example.com(占位地址,请替换为实际渠道)
- 响应:5 个工作日内首次确认(示例承诺,按团队实际能力修改)

还没确定的部分#

GitHub 是否为这个文件提供模板、是否对内容做校验、在私有仓库中是否同样展示,本次材料未涉及,不能据此推断官方态度,待核实。在确认之前,稳妥做法是:按普通 Markdown 写,不依赖任何特定字段,把信息本身写清楚——即使展示方式发生变化,内容对读者仍然成立。

判断标准可以很简单:一个使用读屏软件的开发者读完这份文件,能不能知道哪里会卡住、卡住时怎么办、找谁反馈。能,就写对了。

常见问题(FAQ)

ACCESSIBILITY.md 与在 README 里补一段无障碍说明,有什么实际差别?
两者的差别取决于 GitHub 如何展示这个文件,本次材料未包含该细节,待核实。从维护角度看,独立文件更容易单独演进、单独引用,也不会挤占 README 的入门信息。
完全没做过无障碍测试,还应该建这个文件吗?
可以建,但要把内容限定在“已知情况”上:说明哪些环境未测试、已知障碍在哪里、问题往哪报。不要在其中写“已支持某读屏软件”这类没有验证过的句子。

参考来源

  1. Accessibility statements now have a home on GitHub

以上为本文写作时的参考资料,引用观点以原文为准。

作者:沐小悠

本文约 6 分钟读完 · 关键词:ACCESSIBILITY.md、无障碍声明、GitHub、无障碍目标、已知障碍

更多文章 GET 示例接口

「」标签下的其他文章