Front-End-Checklist 指南基于 W3C 标准校验 HTML构建跨浏览器稳定、可访问的前端页面【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist无效的 HTML 会导致浏览器渲染结果不可预测、破坏辅助技术如屏幕阅读器的正常工作并让线上问题排查变得异常困难。本文基于 Front-End-Checklist 仓库中的w3c-compliant规则SKILL.md 与 references/rule.md为核心骨架系统讲解 W3C HTML 校验的必要性、常见错误的修复方法、自动化校验工具链CLI、构建工具、CI/CD、测试框架的接入方式并结合仓库源码给出可落地的检查、修复、评审与验证流程。读完本文你将掌握从手写合规标签到流水线自动拦截非法 HTML的完整实战能力。为什么必须校验 HTML 是否符合 W3C 标准W3C HTML 校验的本质是确保你最终交给浏览器的标记语言markup符合 Web 标准从而换取三方面的确定性跨浏览器兼容不同浏览器对非法标记的容错解析规则并不完全一致合法 HTML 能让各浏览器的解析行为可预期可访问性辅助技术如屏幕阅读器依赖语义化、结构完整的 DOM 来构建无障碍树标签闭合错误、缺失属性会直接破坏这一链条可维护性结构正确的 HTML 更容易被自动化工具解析、被团队审阅、被搜索引擎与 LLM/Agent 理解。Front-End-Checklist 在 packages/content/rules/en/html/w3c-compliant.mdx 中把该规则归入html分类、best-practices子类优先级为high难度为beginner预估耗时 15 分钟。同时它是 HTML Foundations 清单 中的第 12 项与其他基础项doctype、charset、viewport、lang-attribute、unique-id 等共同构成页面外壳的第一道质量闸门。清单文档特别强调两条审查原则先检查模板再检查页面内容在浏览器中核对真实 DOM 输出而非只盯 JSX 或模板代码——这正好对应本规则的核心要求校验最终面向浏览器的标记而不是源框架抽象层这也是 SKILL.md 中aiContext元数据反复强调的要点。常见校验错误与修复一张对照表规则文档references/rule.md给出了 5 类最常见的违规模式每类都配了错误写法 ❌ / 正确写法 ✅对照示例错误类型❌ 错误示例✅ 正确示例修复要点未闭合标签divpSome contentspanMore content/divdivpSome content/pspanMore content/span/div所有非 void 元素必须显式闭合缺少必需属性img srcimage.jpg、input typetextimg srcimage.jpg altDescription、input typetext nameusername idusername图片必须提供alt表单控件补齐name/id非法嵌套pdivBlock element inside paragraph/div/pdivpParagraph content/p/div块级元素不能嵌入p等短语内容容器重复 ID两个div idcontentidmain-content与idsidebar-content唯一化文档内 ID 必须全局唯一缺失 DOCTYPEhtmlheadtitlePage/title/head!DOCTYPE htmlhtml langenheadmeta charsetUTF-8titlePage/title/head必须声明!DOCTYPE html并补充lang、charset这条规则与仓库内多条兄弟规则互为印证unique-id规则packages/content/rules/en/html/unique-id.mdx专门处理 ID 唯一性其最佳实践建议为相关元素做命名空间化例如modal-login、modal-login-title、modal-login-closelang-attribute与html5-semantic-elements则分别强化lang属性与语义元素的使用。规则元数据relatedRules还列出clean-up-comments、form-validation、direction-attribute、styles-lint见 packages/content/rules/en/css/styles-lint.mdx它们同属html/best-practices区域常常在同一份代码评审中一起被提出——修复时建议联动处理。接入校验工具从在线验证到 CLI 自动化在线与浏览器端校验使用 W3C 官方 Markup Validatorvalidator.w3.org上传文件、输入 URL 或直接粘贴 HTML 进行校验使用 Nu Html Checkervalidator.w3.org/nu/在规则元数据resources中被标记为 tool 类型做接口化校验支持?outjson、?outtext等输出格式安装浏览器扩展在开发阶段即时提示。html-validate CLI规则文档推荐的本地化主力工具是html-validate# 全局安装 npm install -g html-validate # 校验单个文件 html-validate index.html # 校验目录下所有 HTMLglob 展开 html-validate src/**/*.html # 指定配置文件 html-validate --config .htmlvalidate.json src/配置文件.htmlvalidate.json详解{ extends: [html-validate:recommended], rules: { void-style: [error, omit], close-order: error, doctype-html: error, no-missing-references: error, require-sri: error, no-inline-style: warn, element-required-attributes: error, element-permitted-content: error, element-permitted-parent: error }, elements: [html5] }各规则含义void-style: [error, omit]void 元素如img、br的自闭合斜杠按 HTML5 规范省略close-order: error标签必须按先进后出顺序闭合doctype-html: error必须存在!DOCTYPE htmlno-missing-references: error引用如锚点href#id必须指向存在的目标require-sri: error外部脚本/样式建议启用 SRI 子资源完整性校验对应仓库规则 subresource-integrityno-inline-style: warn内联样式作为警告而非错误element-required-attributes/element-permitted-content/element-permitted-parent分别约束元素必需属性、允许的内容模型与允许的父元素——这三条直接覆盖上表中缺少必需属性与非法嵌套两类问题。构建工具集成Webpack / Gulp / Grunt// webpack.config.js —— 打包产物即时校验 const HtmlValidatePlugin require(html-validate/webpack) module.exports { plugins: [ new HtmlValidatePlugin({ configFile: .htmlvalidate.json }) ] }// gulpfile.js —— 构建后流水线校验输出 JSON 报告 const gulp require(gulp) const htmlValidator require(gulp-html-validator) gulp.task(validate-html, () { return gulp.src(dist/**/*.html) .pipe(htmlValidator({ format: json, validator: https://validator.w3.org/nu/ })) .pipe(gulp.dest(reports/)) })// Gruntfile.js —— 使用 grunt-htmllint module.exports function(grunt) { grunt.initConfig({ htmllint: { all: { options: { ignore: [ Bad value X-UA-Compatible for attribute http-equiv on element meta. ] }, src: [dist/**/*.html] } } }) grunt.loadNpmTasks(grunt-htmllint) grunt.registerTask(validate, [htmllint]) }框架层校验React、Next.js 与 VueReact JSX 静态检查在 ESLint 中通过react与jsx-a11y插件从源码层拦截常见问题// .eslintrc.js module.exports { extends: [plugin:react/recommended], plugins: [react, jsx-a11y], rules: { react/jsx-no-duplicate-props: error, react/jsx-no-undef: error, react/jsx-uses-vars: error, react/no-unescaped-entities: error, react/self-closing-comp: error, jsx-a11y/alt-text: error, jsx-a11y/img-redundant-alt: error } }再配合一个自我校验的组件包装器把必需属性强制到组件契约层面import React from react import PropTypes from prop-types function ValidatedImage({ src, alt, ...props }) { if (!alt) { console.error(ValidatedImage: alt attribute is required for accessibility) } if (!src) { console.error(ValidatedImage: src attribute is required) } return img src{src} alt{alt} {...props} / } ValidatedImage.propTypes { src: PropTypes.string.isRequired, alt: PropTypes.string.isRequired } export default ValidatedImage这正呼应了 SKILL.md 中description的一句话不要只校验源码框架抽象层要校验最终面向浏览器的标记。JSX 静态规则解决源码层问题html-validate/Nu Html Checker 解决渲染层问题两层必须都做。Next.js自定义 Document 构建期校验// next.config.js —— 开发环境注入 html-validate 构建插件 const withBundleAnalyzer require(next/bundle-analyzer) module.exports withBundleAnalyzer({ enabled: process.env.ANALYZE true, reactStrictMode: true, webpack: (config, { dev, isServer }) { if (dev !isServer) { config.plugins.push( new (require(html-validate/webpack))({ configFile: .htmlvalidate.json }) ) } return config }, experimental: { strictNextHead: true } })// pages/_document.js —— 控制服务端渲染的 HTML 外壳 import { Html, Head, Main, NextScript } from next/document export default function Document() { return ( Html langen Head meta charSetutf-8 / /Head body Main / NextScript / /body /Html ) }要点lang、charset这类全局属性只在_document.js中声明一次即可保证所有路由共享合规的外壳把校验插件限定在dev !isServer环境避免拖慢生产构建。Vue 3webpack 插件 vue-eslint 规则// vue.config.js —— 仅在开发环境启用 module.exports { chainWebpack: config { if (process.env.NODE_ENV development) { config.plugin(html-validate) .use(require(html-validate/webpack), [{ configFile: .htmlvalidate.json }]) } } }// .eslintrc.js for Vue —— 模板层规范 module.exports { extends: [ plugin:vue/vue3-essential, plugin:vue/vue3-strongly-recommended ], rules: { vue/html-self-closing: [error, { html: { void: always, normal: never, component: always } }], vue/max-attributes-per-line: [error, { singleline: 3, multiline: 1 }], vue/require-v-for-key: error, vue/no-duplicate-attributes: error } }CI/CD 集成让非法 HTML 无法合入主线GitHub Actions# .github/workflows/html-validation.yml name: HTML Validation on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: validate-html: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 18 cache: npm - name: Install dependencies run: npm ci - name: Build project run: npm run build - name: Validate HTML run: | npm install -g html-validate html-validate dist/**/*.html - name: W3C Validation uses: Cyb3r-Jak3/html5validator-actionv7.2.0 with: root: dist/ css: true - name: Upload validation report uses: actions/upload-artifactv3 if: failure() with: name: html-validation-report path: validation-report.jsonGitLab CI# .gitlab-ci.yml stages: - build - validate build: stage: build script: - npm ci - npm run build artifacts: paths: - dist/ validate-html: stage: validate dependencies: - build script: - npm install -g html-validate - html-validate dist/**/*.html - | curl -H Content-Type: text/html; charsetutf-8 \ --data-binary dist/index.html \ https://validator.w3.org/nu/?outjson artifacts: reports: junit: validation-report.xml流程共性先npm ci安装依赖 → 构建出dist/产物 → 用html-validate做离线静态校验 → 再用 W3C 官方 Nu Html Checker 做线上权威校验GitLab 示例通过curl以--data-binary提交 HTML 内容GitHub 示例则使用html5validator-action并开启css: true连带校验样式表→ 失败时上传报告工件。Pre-commit 钩子提交前拦截# 安装 pre-commit pip install pre-commit# .pre-commit-config.yaml repos: - repo: local hooks: - id: html-validate name: HTML Validate entry: html-validate language: node files: \.(html)$ additional_dependencies: [html-validate] - id: w3c-validate name: W3C HTML Validator entry: bash -c for file in $; do curl -H Content-Type: text/html; charsetutf-8 --data-binary $file https://validator.w3.org/nu/?outtext | grep -q Error exit 1; done -- language: system files: \.(html)$ # 安装钩子 pre-commit install说明Front-End-Checklist 仓库本身使用 Lefthook见 lefthook.yml管理 Git 钩子pre-commit是规则文档给出的通用替代方案无论选择哪种钩子框架核心思想一致——在错误进入代码库之前就把它拦下来。自定义校验规则与测试集成用 cheerio 构建自有校验器当团队有专属规范如所有图标必须带aria-hidden时可以基于 cheerio 快速扩展// custom-html-validator.js const fs require(fs) const path require(path) const cheerio require(cheerio) class CustomHTMLValidator { constructor(options {}) { this.rules options.rules || [] this.errors [] this.warnings [] } addRule(rule) { this.rules.push(rule) } validateFile(filePath) { const content fs.readFileSync(filePath, utf8) const $ cheerio.load(content) this.rules.forEach(rule { try { rule.validate($, filePath, this) } catch (error) { this.addError(Rule ${rule.name} failed: ${error.message}) } }) return { errors: this.errors, warnings: this.warnings, isValid: this.errors.length 0 } } addError(message, line null, column null) { this.errors.push({ message, line, column, type: error }) } addWarning(message, line null, column null) { this.warnings.push({ message, line, column, type: warning }) } } // 内置规则alt 文本 / lang 属性 / 内联样式 const requireAltText { name: require-alt-text, validate($, filePath, validator) { $(img).each((i, img) { const $img $(img) if (!$img.attr(alt)) { validator.addError(Image missing alt attribute in ${filePath}) } }) } } const requireLangAttribute { name: require-lang, validate($, filePath, validator) { if (!$(html).attr(lang)) { validator.addError(HTML element missing lang attribute in ${filePath}) } } } const noInlineStyles { name: no-inline-styles, validate($, filePath, validator) { $([style]).each((i, element) { validator.addWarning(Inline styles found in ${filePath}) }) } } // 使用 const validator new CustomHTMLValidator() validator.addRule(requireAltText) validator.addRule(requireLangAttribute) validator.addRule(noInlineStyles) const result validator.validateFile(dist/index.html) console.log(result)接入 Jest 与 CypressJest 侧用 jsdom 对构建产物做结构断言DOCTYPE、html/head/body、lang、charset、图片alt、ID 唯一性// __tests__/html-validation.test.js const fs require(fs) const path require(path) const { JSDOM } require(jsdom) describe(HTML Validation, () { const htmlFiles fs.readdirSync(dist) .filter(file file.endsWith(.html)) .map(file path.join(dist, file)) test.each(htmlFiles)(should be valid HTML: %s, (filePath) { const content fs.readFileSync(filePath, utf8) const dom new JSDOM(content) const document dom.window.document expect(document.doctype).toBeTruthy() expect(document.querySelector(html)).toBeTruthy() expect(document.querySelector(head)).toBeTruthy() expect(document.querySelector(body)).toBeTruthy() const htmlElement document.querySelector(html) expect(htmlElement.getAttribute(lang)).toBeTruthy() const charset document.querySelector(meta[charset]) expect(charset).toBeTruthy() const images document.querySelectorAll(img) images.forEach(img { expect(img.getAttribute(alt)).not.toBeNull() }) const elementsWithIds document.querySelectorAll([id]) const ids Array.from(elementsWithIds).map(el el.id) const uniqueIds [...new Set(ids)] expect(ids.length).toBe(uniqueIds.length) }) })Cypress 侧既做结构断言也可把页面 HTML 实时 POST 给 W3C 接口做端到端校验// cypress/e2e/html-validation.cy.js describe(HTML Validation, () { it(should have valid HTML structure, () { cy.visit(/) cy.document().should(have.property, doctype) cy.get(html).should(have.attr, lang) cy.get(meta[charset]).should(exist) cy.get(img).each(($img) { cy.wrap($img).should(have.attr, alt) }) cy.get([id]).then(($elements) { const ids $elements.toArray().map(el el.id) const uniqueIds [...new Set(ids)] expect(ids.length).to.equal(uniqueIds.length) }) }) it(should pass W3C validation, () { cy.visit(/) cy.get(html).then(($html) { const htmlContent $html[0].outerHTML cy.request({ method: POST, url: https://validator.w3.org/nu/?outjson, headers: { Content-Type: text/html; charsetutf-8 }, body: htmlContent }).then((response) { const errors response.body.messages.filter(msg msg.type error) expect(errors).to.have.length(0) }) }) }) })合法 HTML 的性能收益与线上监控解析性能与兼容性非法嵌套如块级元素嵌入内联容器、未闭合段落会让浏览器进入容错解析路径解析行为随浏览器版本漂移。规则文档给出对照错误写法divpUnclosed paragraphspanNested contentdivBlock in inline/div/div会触发隐式闭合与节点迁移正确写法divpProperly closed paragraph/pdivspanProperly nested content/span/div/div则保证解析树与源码结构一致DOM 可预测、布局稳定这同时也与仓库中的 cumulative-layout-shift 等性能规则目标一致文档目录见 packages/content/rules/en/performance。生产环境解析错误监控// 捕获并上报 HTML 解析/资源加载错误 window.addEventListener(error, (event) { if (event.target.tagName) { console.error(HTML parsing error:, { element: event.target.tagName, source: event.target.src || event.target.href, message: event.message }) analytics.track(html_parsing_error, { element: event.target.tagName, url: window.location.href }) } })将这类错误接入错误监控体系本仓库前端应用通过 instrumentation.ts 与 Sentry 配置接入监控就能把静态校验漏网之鱼在生产环境第一时间暴露出来。最佳实践与常见错误清单规则文档归纳的 8 条最佳实践尽早且频繁校验把校验嵌入日常开发流程自动化校验依赖构建工具与 CI/CD 流水线立即修复错误不要累积校验债务使用语义化 HTML正确的结构本身就能提高校验通过率对应 html5-semantic-elements跨浏览器测试合法 HTML 是兼容性的前提生产环境监控跟踪与 HTML 相关的错误团队教育让每个开发者理解 HTML 标准记录例外打破标准时必须说明理由如兼容旧版 IE 的 meta 写法可在 Grunt lint 配置的ignore数组中显式登记。常见错误速查8 类未闭合标签——所有非 void 标签必须正确闭合缺少alt属性——可访问性的硬性要求重复 ID——文档内必须唯一非法嵌套——块级元素不能放进内联元素缺失 DOCTYPE——标准模式的前提缺失lang属性——影响可访问性与翻译工具过时元素——改用现代语义元素非法属性——检查属性名与取值。标准依据与验证流程以哪个标准为准规则元数据sources明确了两份权威依据MDN: HTMLtype: mdnauthority: primary以最终渲染 HTML 与浏览器面向行为为准WHATWG HTML Living Standardtype: specauthority: primary以最终渲染 HTML 与浏览器面向行为为准。注意这里的措辞是最终渲染的 HTML 与浏览器面向行为——即校验对象必须是运行时产物而不是 JSX/Vue 模板等源码抽象。自动化验证清单Verification在浏览器或页面源码中检查最终渲染的 HTML确认规则得到满足用浏览器开发者工具或 HTML 校验器验证受影响标记测试一个使用该模式的有代表性路由或模板复查输出相同标记的共享组件确保修复保持一致避免修一处、漏十处。手动验证清单在代表性路由与受支持浏览器上手动验证渲染后的浏览器行为确保用户可见结果与规则预期一致。这套自动化 手动的双层验证流程与 SKILL.md 的 Check / Fix / Explain / Code Review 四段式工作流一一对应Check阶段用校验器定位问题Fix阶段修复错误未闭合标签、缺失属性、非法嵌套Explain阶段向团队解释 W3C 校验对兼容性、可访问性与可维护性的意义Code Review阶段审查模板、服务端渲染 HTML 与共享组件并精确指出违规的具体元素、属性与路由。在 Front-End-Checklist 中的应用延伸本规则在内容仓库中的正式定义packages/content/rules/en/html/w3c-compliant.mdx包含tldr、whyItMatters、promptscheck/fix/explain/codeReview、sources、relatedRules等结构化元数据可直接被 Agent 消费Agent 可执行技能SKILL入口skills/w3c-compliant/SKILL.md完整实现细节见 references/rule.md归属清单HTML Foundations 清单适合新页面模板、共享布局/表单组件重构、以及小问题反复出现的全站审计场景其审查技巧先模板后页面、核对浏览器 DOM、把重复错误上升为设计系统/框架问题正是本规则落地的实操心法。把校验从上线前的一次性动作变成开发—构建—测试—提交—部署全链路自动拦截的常态机制你就能用最小成本换来可预测的跨浏览器渲染、稳定的无障碍体验和长期可维护的 HTML 代码库。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考