post-build 工具无法安全修复可访问性问题，因其根源在 HTML 结构层（如 div 冒充按钮、label/input ID 不匹配、缺失 lang 属性），而扫描工具不敢自动重写 DOM 以免破坏 JS 或 CSS；必须将校验前置到模板/组件层并强制语义约束。
为什么不能靠 post-build 工具自动修复可访问性问题
可访问性缺陷大多在 HTML 结构层就已固化，比如 div 冒充按钮、label 和 input 的 id/for 不匹配、缺失 lang 属性——这些不是样式或 JS 行为问题，而是 DOM 语义错误。Lighthouse 或 axe CLI 这类扫描工具只能报错，无法安全地重写结构：它不敢把 <div class="btn">提交</div> 自动替换成 <button>提交</button>，因为可能破坏 JS 绑定或 CSS 选择器逻辑。
常见错误现象：
- 构建后报告 “
Form elements do not have associated labels”，但源码里明明写了<label>—— 实际是构建时模板引擎拼接 ID 出错，如id="user_email_{{id}}"和for="user-email"不一致 - 多语言项目中，
aria-label硬编码英文字符串，构建产物里无法随 locale 切换 -
<nav>没加aria-label，但自动化检查只提示“缺少 label”，不说明该补什么内容
如何在模板/组件层强制约束语义结构
把可访问性规则下沉到编写阶段，比后期检测更有效。关键不是加更多 lint 规则，而是让错误写法根本“写不出来”。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 使用 JSX 或 Vue SFC 时，用 ESLint 插件
eslint-plugin-jsx-a11y检查htmlFor和id是否匹配，且禁止role="button"出现在非button元素上 - 自定义 Button 组件必须接受
asChild或asprop（如 Radix UI），默认渲染<button>，仅当明确需要a或span时才降级，且自动注入tabIndex和键盘事件 - 表单字段组件（如
TextInput）强制要求传入labelText或aria-label，否则编译报错；内部自动生成唯一id并同步到label的htmlFor - 所有
<nav>必须带aria-label属性，模板校验器（如 Astro 的@astrojs/check）可拦截空值或泛化值（如"Navigation"）
构建流程中哪些环节必须插入可访问性检查
CI 流程里只跑 Lighthouse 是低效的：它测的是最终页面，问题定位成本高。应分层卡点，在更早阶段暴露问题。
推荐插入点：
-
pre-commit：用
axe-core的rendered模式检查组件快照（如 Jest + axe），验证<MyTabList>渲染后是否含role="tablist"、每个tab有aria-selected，避免“写了 ARIA 却没生效” -
build step：用
html-validate扫描产出的 HTML 文件，规则包括require-lang-attribute、require-label、no-distracting-elements（禁用marquee、blink） - preview deploy：对 Storybook 或 Chromatic 链接运行 axe CLI，生成可访问性报告并阻断 PR 合并，阈值设为“零严重错误（critical）”
动态内容与 SSR 场景下的易漏点
服务端渲染（SSR）或静态站点生成（SSG）时，可访问性风险更隐蔽：HTML 在服务端生成，但焦点管理、aria-live 更新、状态同步全在客户端补，容易脱节。
容易踩的坑：
- SSR 页面初始渲染时，
aria-current="page"被正确写入，但客户端路由切换后未更新——读屏器仍停留在旧步骤 - 加载状态用
<div aria-live="polite"></div>，但服务端未预留该节点，JS 初始化时才 append，导致首次播报失败 - 多语言切换时，
lang属性在 HTML 根节点由服务端写死（如<html lang="en">），客户端切换 locale 后未同步更新，NVDA 仍按英文朗读 - 表单错误提示依赖
aria-describedby指向一个<div id="error-123">，但该 div 在 SSR 中未渲染（因初始无错误），客户端 JS 插入后 ID 冲突或未及时绑定
复杂点不在“怎么加 ARIA”，而在于语义生命周期是否与渲染逻辑对齐——服务端输出的 HTML 必须是完整、自洽的无障碍起点，而不是留一堆“等 JS 来修”的坑。
