W3C验证器对SPA模板无效，它只校验纯HTML5语法，不解析Vue/React等框架语法；必须验证构建后的dist/index.html或SSR输出的静态HTML，而非.vue/.tsx源文件。
W3C验证器对SPA模板是否有效
直接把 Vue/React 组件的 .vue 或 .tsx 源文件丢进 W3C 验证器，大概率报满屏错误——它不理解 <template>、v-if、{% raw %}{{ count }}{% endraw %} 这类语法，只认纯 HTML5 文档。真正该验证的是：服务端渲染（SSR）输出的首屏 HTML，或构建后 dist/index.html 中由框架注入的静态骨架。
常见错误现象：Element “v-if” not allowed as child of element “div” —— 这不是你代码错了，是验证器在“读源码”，而非“读运行结果”。
- 正确做法：用 Puppeteer 启动无头浏览器，访问本地 dev server 或 build 后页面，再用
page.content()获取真实 DOM 字符串，喂给 W3C API 或本地html-validate - 若用 Vite/Next.js 等支持 SSR 的框架，可在
build后检查dist/server/index.html（如有） - 跳过
<script setup>和<style scoped>块，它们不属于 HTML 语义层校验范围
如何检测组件级语义缺失与 a11y 断点
单页应用里，<main>、<nav> 等语义标签常被动态插入或条件渲染，传统扫描工具容易漏掉。关键不是“有没有写”，而是“运行时是否存在且唯一”。
例如：路由切换后，新页面没补上 <main>，或多个 v-for 渲染的卡片都用了 role="region" 却没配 aria-labelledby，屏幕阅读器就会迷失。
立即学习“前端免费学习笔记（深入）”；
React 与 Next.js 性能优化指南，源自 Vercel 工程团队。适用于编写、审查或重构 React/Next.js 代码时使用。
- 用 Axe CLI 在真实浏览器上下文中运行：
npx axe-core http://localhost:5173 --tags=wcag2a,wcag2aa，它能捕获 JS 动态生成后的可访问性问题 - 在 Cypress/Playwright 测试中加断言：
expect(await page.$('main')).not.toBeNull()，确保每个路由响应都含语义主容器 - 避免在组件模板里硬编码
alt=""；若图片为装饰性，必须显式加role="presentation"，否则会被读屏器误读为空白内容
HTMLHint 无法覆盖的 SPA 特有风险点
htmlhint 能查 img 缺 alt、button 缺 type，但它看不到 Vue 的 v-bind:alt="user.avatarDesc || ''" 是否实际为空字符串——这会导致 a11y 失效，但静态扫描完全通过。
更隐蔽的是资源加载时机耦合：比如组件内 <img :src="avatarUrl" @error="fallbackToDefault"，若 fallbackToDefault 方法未定义或拼错，控制台报 TypeError: _this.fallbackToDefault is not a function，但 HTML 结构本身“完全合法”。
- 必须结合运行时监控：在全局
window.addEventListener('error', handler)中捕获此类 JS 错误，并关联当前路由和组件名（可通过document.querySelector('[data-v-xxxx]')反查） - 对动态属性做防御性检查：如
<img :alt="desc || '用户头像'">，比:alt="desc"更安全 - 禁止在模板中使用
javascript:void(0)或#作链接 href，Vue Router 的<router-link>才是正解；否则 Lighthouse 会扣分且影响键盘导航
CI 流程中如何让 HTML 质量检查不拖慢构建
每次 git push 都跑一次全站 Puppeteer + Axe 扫描？没必要，也扛不住。重点应放在“变更影响面”——只检测本次修改涉及的组件产出的 HTML 片段。
例如：改了 UserCard.vue，就只提取它编译后对应的 DOM 快照（可用 @vue/test-utils mount + element.outerHTML），再喂给 html-validate 和 axe-core 的轻量模式。
- 用
git diff --name-only提取改动的 .vue/.tsx 文件，映射到对应路由或组件测试用例 - 跳过第三方 UI 库（如 Element Plus、Ant Design）的模板，专注业务组件；它们的质量应由库自身保障
- 把 HTML 质量检查设为非阻断项（warning 级别），但要求 PR 描述中注明已修复的 a11y 问题编号（如 WCAG 1.1.1）
最常被忽略的一点：组件模板里的 data-testid 属性，既不能提升质量，也不参与校验——它只是个定位钩子。真正决定质量的，是那个 aria-live="polite" 是否在状态更新时准确触发，以及 tabindex 是否随 v-if 正确增删。这些，只有在 DOM 真实存在时才能验证。
