Front-End-Checklist 规则目录全解析:385 条前端检查规则的分类体系与生成机制
本篇技术指南围绕 Front-End-Checklist 仓库中自动生成的规则目录 docs/generated/rules-catalog.md 展开,完整拆解其数据来源、11 大分类的构成、四档优先级体系、单条规则的 frontmatter 结构,以及"一条规则从内容编写到目录生成再到站点/Agent 消费"的完整链路。读完本文,你将掌握如何阅读、定位、验证与扩展这套由 385 条规则组成的前端质量知识库,并能用同样的机制为项目构建可被搜索引擎与 LLM 检索的规则目录。
规则目录是什么:一份由 385 条规则驱动的"活文档"
Front-End-Checklist 的核心资产并非代码,而是 packages/content/rules/en/ 目录下以 Markdown 文件(.mdx)形式组织的 385 条英文前端检查规则。这些规则覆盖了现代 Web 开发的方方面面——从 HTML 语义化、CSS 布局、JavaScript 运行时质量,到性能指标、无障碍、SEO、安全、图片、测试、隐私与国际化。
规则目录 是这 385 条规则的全量索引清单:每条规则一行,包含规则标题、所属分类、优先级徽章与一句话描述。它的第一行注释清楚地说明了它的性质:
<!-- Generated from rule frontmatter. Do not edit manually. Run `pnpm generate:readme`. -->
这意味着该文件不是手工维护的文档,而是由脚本从规则的 frontmatter 元数据自动生成的产物。修改规则内容后,运行 pnpm generate:readme 即可重新生成目录,保证"规则内容"与"目录索引"永远同步。
目录如何生成:从 frontmatter 到 Markdown 的自动化链路
生成机制的核心实现在 scripts/generate/generate-readme.ts 中,其数据流如下:
- 读取规则目录:脚本遍历
packages/content/rules/en/下 11 个分类子目录,筛选所有.mdx文件(见loadRuleEntries,generate-readme.ts)。 - 解析 frontmatter:使用
gray-matter读取每个文件的 YAML 元数据,提取title、description、categories、priority字段;缺失时以文件名作为 title、以No description available.兜底,优先级默认回落为medium(见resolveRulePriority,generate-readme.ts)。 - 归类与排序:分类归属优先取 frontmatter 中
categories[0],否则按文件所在目录推断;规则最终按RULE_CATEGORIES定义的分类顺序 + 标题字母序排序(见resolveRuleCategory,generate-readme.ts)。 - 生成两处产物:
buildReadmeCatalogMarkdown:生成根目录README.md中<!-- rules-catalog:start -->与<!-- rules-catalog:end -->标记之间的紧凑版目录(带分类锚点与站点外链);buildFullCatalogMarkdown:生成完整的 rules-catalog.md,即本文讨论的全量目录。
- 更新统计:脚本还会同步 README 中"
NEnglish rules acrossMactive categories"的统计数字(见replaceReadmeStats,generate-readme.ts)。
replaceRulesCatalog 对 README 中的起止标记有严格校验:必须恰好存在一对 start/end 标记且顺序正确,否则直接抛错——这从机制上防止了目录块被意外破坏(generate-readme.ts)。
分类的展示名与描述同样由脚本内置的 CATEGORY_DISPLAY 映射控制,例如 html → "HTML / Semantic markup, metadata, forms, and document structure rules."、seo → "SEO / Crawlability, metadata, structured data, and search visibility rules."(generate-readme.ts)。
11 大分类全景:规则如何被组织
规则分类的权威枚举定义在 packages/rules/src/types.ts 的 RULE_CATEGORIES 中。目录实际输出 11 个活跃分类(pwa 分类在枚举中存在但当前无规则文件,故不输出)。下表为全景概览:
| 分类 | 规则数量 | 关注主题 |
|---|---|---|
| HTML | 25 | 语义化标记、元数据、表单、文档结构 |
| CSS | 32 | 布局、排版、响应式设计、样式规则 |
| JavaScript | 26 | 客户端行为、异步模式、运行时质量 |
| Performance | 43 | 加载速度、渲染、优化、Core Web Vitals |
| Accessibility | 95 | 键盘、屏幕阅读器、ARIA、包容性 UX |
| SEO | 94 | 可爬取性、元数据、结构化数据、搜索可见性 |
| Security | 22 | 响应头、传输、安全链接、前端安全 |
| Images | 25 | 格式、响应式交付、优化、媒体质量 |
| Testing | 13 | 单元、集成、E2E、监控、质量保证 |
| Privacy | 5 | 同意、追踪、数据保留、用户数据权利 |
| Internationalization | 5 | 本地化、RTL、语言处理、翻译工作流 |
| 合计 | 385 | — |
Accessibility 与 SEO 合计 189 条,占总量的近一半,反映出项目对"可访问性"与"搜索引擎可见性"的倾斜——这两类规则既是硬性合规(如 WCAG 2.1),也是内容质量的核心。
以下按分类完整列出全部 385 条规则(沿用目录的标题 + 优先级 + 描述结构)。
HTML(25 条)
- Add Subresource Integrity to external scripts(High):为来自 CDN 的外部脚本与样式表添加 SRI 哈希属性,确保内容未被篡改。
- Add thumbnail images to videos(Medium):HTML5 视频元素应提供
poster属性,在视频加载或播放前显示缩略图。 - Create a custom 404 error page(Medium):自定义 404 页面应包含对迷失用户的导航帮助。
- Declare UTF-8 character encoding(Critical):
charset(UTF-8)必须作为 head 中第一个元素正确声明。 - Ensure all IDs are unique(High):文档内所有 ID 属性唯一,页面上不存在重复 ID。
- Implement accessible breadcrumb navigation(Medium):面包屑导航使用正确的语义标记与 ARIA 属性实现无障碍。
- Implement favicons for all devices(Medium):为浏览器、设备与 PWA 支持实现所有必需的 favicon 格式。
- Link a Web App Manifest for installability(Medium):在 HTML head 中链接 Web App Manifest(manifest.json),启用主屏安装、独立显示与启动屏等 PWA 能力。
- Load scripts with defer, async, or type=module(High):使用
defer、async或type=module防止 JavaScript 阻塞 HTML 解析。 - Make custom elements and Web Components accessible(Medium):自定义元素必须通过
ElementInternals实现 ARIA 反射、键盘交互与表单关联。 - Make file uploads accessible(Medium):文件上传组件具备正确的标签、文件类型限制与进度反馈。
- Make pagination accessible(Medium):分页控件具备 ARIA 标签、键盘导航与当前页指示。
- Make search inputs accessible(Medium):搜索功能具备正确的 input 类型、标签、role 与自动补全建议。
- Make videos accessible with captions(High):视频具备字幕、音频描述、文字稿、暂停控制并避免自动播放。
- Meet PWA installability criteria(Low):满足浏览器的 PWA 可安装性最低要求:有效 manifest、注册 service worker、HTTPS 与 maskable 图标。
- Provide noscript fallback content(Medium):为禁用 JavaScript 的用户提供
noscript回退内容。 - Remove comments and debug code in production(Medium):部署前移除多余代码、注释与调试元素。
- Set text direction for RTL languages(Medium):为从右向左(RTL)或混合内容语言使用
dir属性。 - Set the page lang attribute(High):
<html>元素必须带有合法 BCP 47 语言代码的lang属性。 - Set the responsive viewport meta tag(Critical):为响应式设计正确声明 viewport meta 标签。
- Use semantic HTML elements(High):恰当使用 HTML5 语义元素(header、section、footer、main、article、aside 等)。
- Use semantic input type attributes(High):为 input 元素设置正确的
type属性以触发正确的移动键盘、浏览器校验与自动填充。 - Use the HTML5 doctype(Critical):HTML5 doctype 声明必须是每个 HTML 文档的第一行,以触发所有浏览器的标准模式渲染。
- Validate forms accessibly(High):表单提供清晰的校验反馈,附带无障碍错误信息与正确的 ARIA 属性。
- Validate HTML against W3C standards(High):HTML 标记按 W3C 标准校验以保证跨浏览器兼容。
CSS(32 条)
- Apply Flexbox best practices(Medium):为一维布局正确使用 Flexbox,避免过度使用
flex:1、忽略min-width:0、误解flex-basis等常见错误。 - Avoid embedded and inline CSS(High):除关键 CSS 与性能优化外,避免内嵌与内联 CSS。
- Avoid intrusive interstitials(Medium):移动端遮挡主内容的全屏插屏(弹窗、遮罩、Cookie 横幅)是排名惩罚信号与无障碍障碍,应使用非侵入式替代方案。
- Do not disable pinch zoom(High):viewport meta 标签不得设置
user-scalable=no或maximum-scale=1,否则违反 WCAG 2.1 SC 1.4.4(文本缩放)。 - Include a print stylesheet(Medium):提供并正确优化打印样式表。
- Inline critical CSS for faster rendering(High):将首屏关键 CSS 内联到 head 中以加速首次渲染。
- Keep CSS specificity low and flat(High):以尽可能低的选择器优先级编写样式,避免 ID 选择器与深层嵌套。
- Lint CSS and SCSS files(Medium):所有 CSS/SCSS 文件用 Stylelint 检查错误并执行标准。
- Load CSS without blocking render(High):非关键 CSS 异步加载以避免阻塞 DOM 渲染。
- Minify all CSS files(High):压缩所有 CSS 文件以减小体积、提升加载性能。
- Optimize web font formats(Medium):Web 字体使用现代格式(WOFF2、WOFF)并具备正确的回退与加载策略。
- Order CSS files correctly(Medium):所有 CSS 文件在 JavaScript 文件之前加载以防阻塞渲染。
- Prevent horizontal scrolling(Medium):标准视口宽度下页面不得出现水平滚动,水平溢出会破坏响应式布局并使缩放用户无法访问内容。
- Provide visible custom focus indicators(High):所有可交互元素必须有清晰可见的焦点指示,切勿只移除默认 outline 而不提供更好的替代。
- Register CSS custom properties with @property for animation and type safety(Low):使用
@property注册带类型、初始值与继承控制的 CSS 自定义属性,实现属性动画与设计令牌编译期校验。 - Remove unused CSS rules(High):移除未使用的 CSS 以减小打包体积并提升性能。
- Support dark mode with prefers-color-scheme(Medium):使用
prefers-color-scheme媒体查询与 CSS 自定义属性实现暗色模式。 - Use :has() to style parent elements based on their descendants(Low):使用
:has()关系伪类基于元素包含的内容选择并设置样式。 - Use @layer to manage CSS cascade order explicitly(Low):使用 CSS 级联层(
@layer)对优先级与级联顺序进行显式、可预测的控制。 - Use a CSS reset or normalize stylesheet(Medium):使用 CSS reset 或 normalize 保证跨浏览器样式一致。
- Use consistent CSS naming conventions(Medium):采用一致的类命名方法论(BEM、CUBE CSS 或团队约定)。
- Use container queries for component-level responsiveness(Medium):使用容器查询让组件响应自身容器尺寸而非视口。
- Use CSS containment to limit repaint scope(Medium):对组件应用
contain属性,告知浏览器其与页面其余部分相互独立,从而优化重绘与回流范围。 - Use CSS custom properties for design tokens(High):将设计系统值(颜色、间距、排版)定义为
:root上的 CSS 自定义属性。 - Use CSS Grid for two-dimensional layouts(Medium):需要同时控制行与列时使用 CSS Grid。
- Use CSS logical properties for i18n and RTL support(Medium):使用逻辑属性(
margin-inline、padding-block、border-inline-start)替代物理属性以自动支持 RTL。 - Use CSS subgrid to align nested grid items to parent tracks(Low):使用
grid-template-columns: subgrid让嵌套网格项参与父网格轨道。 - Use oklch() and oklab() for perceptually uniform colour palettes(Low):设计系统中的颜色值使用
oklch()/oklab()产生感知均匀的调色板。 - Use readable font sizes on mobile(Medium):移动端文本必须大到无需缩放即可阅读,使用相对单位(rem/em)以尊重浏览器字号偏好。
- Use relative units for responsive layouts(High):使用 rem、em、%、vw、vh 与
clamp()替代固定 px。 - Use the View Transitions API for smooth page and component transitions(Low):使用 View Transitions API 实现页面状态或导航间的动画过渡。
- Use transform and opacity for animations(High):使用 CSS
transform与opacity做动画以保持在 GPU 合成器线程以 60fps 运行。
JavaScript(26 条)
- Avoid implicit type coercion(Medium):使用严格相等(
===)与显式类型转换避免隐式类型强制转换的意外结果。 - Avoid inline JavaScript(High):避免内联 JavaScript,保持脚本在外部文件中以便缓存与维护。
- Avoid the any type — use unknown, generics, or type guards instead(Medium):用
unknown、泛型或类型守卫替代 TypeScript 的any类型。 - Debounce and throttle event handlers(High):对 scroll、resize、input 等高频率事件使用防抖或节流。
- Enable noUncheckedIndexedAccess to catch out-of-bounds array bugs(Medium):在 tsconfig.json 启用
noUncheckedIndexedAccess,使数组/对象索引访问返回T | undefined。 - Enable TypeScript strict mode in tsconfig.json(High):在 tsconfig.json 中启用
"strict": true。 - Handle cross-origin requests securely(High):正确使用 CORS、用
postMessage校验消息来源、理解同源策略。 - Implement proper error handling(High):在异步操作与 UI 组件中使用 try-catch 与错误边界。
- Lint JavaScript code(Medium):用 ESLint 检查 JavaScript 代码。
- Minify all JavaScript files(High):压缩所有 JavaScript 文件。
- Minimize costly DOM read/write operations(High):分离批量 DOM 读与写以避免布局抖动(layout thrashing)。
- Never use eval() or unsafe dynamic code execution(Critical):避免
eval()、new Function()、带字符串参数的setTimeout/setInterval与对不可信内容的innerHTML。 - Parse JSON safely with error handling(Medium):始终用 try/catch 包裹
JSON.parse()并在使用前校验解析结构。 - Prefer const and let over var(High):使用块级作用域的
const/let替代函数作用域的var。 - Prefer immutable data patterns(Medium):使用展开运算符与返回新值的数组方法而非原地修改。
- Prevent common memory leak patterns(High):识别并避免常见内存泄漏源:被遗忘的事件监听器、DOM 引用残留、闭包持有大对象、未清理的定时器。
- Remove console statements in production(Medium):部署前移除或禁用
console.log等语句。 - Split large JavaScript bundles(High):使用动态导入与路由级代码分割。
- Use ES modules (import/export)(High):使用原生 ES 模块语法替代 CommonJS
require()。 - Use event delegation for dynamic content(Medium):将事件监听器挂到稳定父元素而非动态子元素上。
- Use import type for type-only imports(Low):对仅作为类型的导入使用
import type语法,编译期完全擦除、零运行时成本。 - Use modern array and object methods(Medium):使用 ES2015+ 的 map、filter、reduce、find、flatMap 与 Object.entries、Object.fromEntries、structuredClone。
- Use scheduler.yield() to keep the main thread responsive during long tasks(Medium):用
scheduler.yield()或 MessageChannel 回退拆分超过 50ms 的长任务。 - Use Web Storage API safely(Medium):正确使用 localStorage/sessionStorage,注意序列化、错误处理与安全。
- Validate external data at runtime with a schema library(High):用 Zod 或 Valibot 校验 API 响应、表单输入、localStorage 与环境变量。
- Write internationalisation-friendly translation strings(Medium):翻译字符串使用 ICU 等消息格式模式,正确处理复数、性别与变量插值。
Performance(43 条)
- Analyze performance with WebPageTest(High):用 WebPageTest 分析页面性能以定位加载瓶颈与优化机会。
- Avoid JavaScript-based redirects(Medium):检测返回 3XX 重定向的 JavaScript 资源以减少延迟。
- Avoid serving legacy JavaScript to modern browsers(Medium):检测 ES5 polyfill 与旧式 JavaScript 代码以减小打包体积。
- Convert animated GIFs to video(Medium):用 MP4 或 WebM 等更高效的视频格式替代大型动图 GIF。
- Disable lazy loading for above-the-fold content(Medium):检测首屏图片上的懒加载以改善 LCP。
- Eliminate render-blocking resources(Medium):检查阻止首次渲染的渲染阻塞 CSS 与 JavaScript。
- Enable browser caching(High):为静态资源正确配置 Cache-Control 与 ETag 响应头。
- Enable HTTP/2 or HTTP/3(High):使用现代 HTTP 协议实现请求多路复用、降低网络延迟。
- Enable text-based compression(High):用 Gzip 或 Brotli 压缩 HTML、CSS、JS 等文本资源。
- Implement Google Consent Mode v2(High):根据用户同意调整 Google Tag 行为以符合隐私法规并保持数据洞察。
- Implement lazy loading for offscreen content(High):对首屏以下图片与重资源启用懒加载。
- Keep page load time under 3 seconds(High):标准连接下页面完全加载在 3 秒以内。
- Keep page weight under 1500KB(High):包含所有资源的总页面重量低于 1500KB(理想低于 500KB)。
- Load non-critical code on user interaction(High):将 JS 模块、组件与第三方代码推迟到用户通过点击、聚焦、悬停等交互表达意图时。
- Load non-critical code when content approaches the viewport(High):使用视口感知加载在内容即将可见时获取组件与功能代码。
- Minimize critical request chains(High):减少阻塞页面首次渲染的依赖请求的数量与深度。
- Minimize cumulative layout shift(High):保持视觉稳定,CLS 得分低于 0.1。
- Minimize HTTP requests(High):通过合并文件、使用雪碧图与 HTTP/2 最小化 HTTP 请求。
- Optimize CSS file size(Medium):保持单个 CSS 文件小巧并移除未使用样式以加速关键渲染路径。
- Optimize first contentful paint(High):首次内容渲染在 1.8 秒内。
- Optimize Google Tag Manager implementation(Medium):高效配置 GTM 以最小化对加载速度与主线程阻塞的影响。
- Optimize interaction to next paint(High):页面在 200ms 内响应用户交互。
- Optimize JavaScript bundle size(Medium):检查超过建议大小限制的 JavaScript 文件。
- Optimize largest contentful paint(Critical):最大内容元素在 2.5 秒内加载完成。
- Optimize pages for back/forward cache(High):避免 unload 监听器等 bfcache 阻塞因素,并正确恢复状态。
- Optimize third-party script loading(High):异步加载第三方脚本以防阻塞主线程。
- Optimize web font loading(High):使用高效字体格式与加载策略防止布局偏移与不可见文本。
- Perform browser-based performance audits(Medium):在完整浏览器环境中执行性能审计以获取准确运行时指标与布局偏移。
- Provide an offline fallback page(Medium):网络不可用时显示自定义离线回退页面而非浏览器通用错误页。
- Provide source maps for production debugging(Medium):检查 source map 的可用性与配置以方便调试。
- Reduce DOM size and complexity(Medium):保持 DOM 树小而浅以改善内存使用与渲染性能。
- Reduce Time to First Byte (TTFB)(Medium):测量并优化服务器响应时间(TTFB)。
- Register a service worker for caching and offline support(Medium):注册 service worker 拦截网络请求、缓存关键资源并启用离线功能。
- Remove duplicate JavaScript libraries(Medium):检测并合并重复的 JavaScript 库以减小体积并防止版本冲突。
- Show loading indicators(High):异步操作期间提供加载指示器告知用户进度。
- Stream HTML to the browser before the full response is ready(Medium):使用 HTTP chunked 传输与 React
renderToPipeableStream(或 ReadableStream)尽早交付 HTML,降低 TTFB 与 FCP。 - Use a content delivery network(High):静态资源由 CDN 提供以降低延迟。
- Use fetchpriority to hint resource loading priority(Medium):对关键图片、脚本与 preload 链接应用
fetchpriority属性。 - Use preconnect for critical third-party origins(Medium):检查对关键第三方来源的 preconnect 提示。
- Use resource hints for faster loading(High):实现 preload、prefetch、preconnect 提示以优化资源加载优先级。
- Use secure and up-to-date JS libraries(Medium):检测 JavaScript 库并检查已知漏洞。
- Use the Speculation Rules API to prefetch and prerender navigations(Low):以声明式方式预取或预渲染可能的下一页面。
- Virtualize long lists and tables(Medium):大型集合只渲染可见行或卡片子集,减小 DOM 大小与内存占用。
Accessibility(95 条)
- Align visible labels with accessible names(Medium):控件的可访问名称应包含其可见标签文本。
- Allow pasting into form inputs(Medium):用户应能将内容粘贴到表单字段中。
- Announce dynamic content with ARIA live regions(High):使用恰当的 ARIA live regions 向屏幕阅读器播报动态内容更新。
- Associate labels with form controls(Critical):表单输入必须有程序化关联的标签。
- Avoid autofocus on form fields(Low):表单字段不使用
autofocus属性以免让屏幕阅读器用户迷失。 - Avoid autoplaying media(High):音视频不自动播放,或立即提供暂停/停止控件。
- Avoid focusable descendants in role="text" elements(Medium):
role='text'元素内不得有可聚焦后代。 - Avoid images of text(Low):使用真实文本而非含文字的图片。
- Avoid meta refresh redirects(Medium):meta refresh 重定向会迷惑用户并造成无障碍问题。
- Avoid redundant entry in the same process(High):多步流程中已提供过的信息应自动填充或可选,而非再次输入。
- Avoid redundant image alternative text(Low):替代文本不应包含 'image'、'photo' 等冗余词。
- Avoid scrolljacking and custom scroll behavior(Medium):保留自然滚动行为,不自定义滚动速度、方向或劫持滚动事件。
- Avoid sensory-only instructions(High):说明不得仅依赖颜色、形状、大小、位置或声音等感官特征。
- Avoid using deprecated ARIA roles(Medium):检查已废弃或抽象的 ARIA 角色以确保长期兼容。
- Create accessible tooltips(Medium):工具提示对键盘用户与屏幕阅读器可访问,具备正确 ARIA 属性与焦点处理。
- Define proper table headers(Medium):检查数据表是否有正确的表头。
- Do not use aria-hidden on the document body(Critical):确保 body 未被设置为
aria-hidden,否则整个页面将向屏幕阅读器隐藏。 - Enable keyboard navigation for all elements(Critical):所有交互元素可通过键盘访问,焦点顺序逻辑且隐藏元素排除在 Tab 序列外。
- Ensure accesskey values are unique(Medium):检查
accesskey值唯一以避免快捷键冲突。 - Ensure all input fields have accessible names(Critical):检查输入字段具有可访问名称,让屏幕阅读器用户知道每个字段期待什么数据。
- Ensure ARIA attributes are valid(High):所有 ARIA 属性必须合法且存在于 WAI-ARIA 规范中。
- Ensure ARIA roles are contained by required parent roles(Medium):检查特定 role 的元素是否位于必需的父 role 内。
- Ensure ARIA roles contain required child roles(High):特定 ARIA role 必须包含必需的子 role,否则组件结构对辅助技术失效。
- Ensure content remains usable without CSS(High):禁用或替换作者 CSS 时,内容结构、说明与主要任务仍可理解与操作。
- Ensure dialogs have an accessible name(Medium):检查 dialog 元素具有可访问名称。
- Ensure headings contain text(Medium):所有标题元素(h1-h6)必须有可见、有描述性的内容。
- Ensure identical links have consistent destinations(Medium):相同文本的链接必须指向相同目的地或可区分。
- Ensure logical focus order(High):Tab 焦点顺序遵循页面视觉布局与逻辑阅读顺序。
- Ensure table headers associate with data cells(Medium):检查表头与数据单元格的关联。
- Ensure tables have unique accessible names(Medium):检查数据表具有唯一可访问名称。
- Fix empty and broken links(High):所有链接包含可访问文本内容且不指向损坏目的地。
- Hide decorative elements from assistive technology(Medium):使用
aria-hidden或空alt向屏幕阅读器隐藏装饰性图片与视觉元素。 - Implement "Skip to Content" links(Medium):检查键盘导航的绕过机制。
- Include a skip navigation link(High):提供跳转导航链接,让键盘用户绕过重复内容直达主要内容。
- Include required ARIA attributes for roles(Medium):检查元素具有其 role 必需的 ARIA 属性。
- Keep focused elements unobscured(High):粘性头部、页脚、横幅与遮罩不得完全隐藏当前拥有键盘焦点的元素。
- Keep repeated help mechanisms in a consistent location(Medium):同一流程多个页面出现的帮助机制保持在相同相对顺序。
- Link table cells to headers using IDs(Medium):检查 td 的
headers属性引用了有效的 th id。 - Maintain logical heading order(Medium):标题层级遵循顺序、层级化的结构。
- Make accordions keyboard navigable(Medium):手风琴组件使用正确的 ARIA 属性与键盘交互。
- Make carousels accessible(Medium):轮播与滑块具备暂停控件、键盘导航与正确 ARIA 属性。
- Make drag and drop accessible(Medium):拖放界面提供键盘替代方案与正确 ARIA 属性。
- Make links in text blocks visually distinguishable(Medium):文本块内的链接必须仅凭颜色之外的方式与周围非链接文本区分。
- Make modal dialogs keyboard accessible(High):模态对话框具备正确的焦点陷阱、ARIA 属性与键盘关闭。
- Make notifications accessible(High):Toast 通知与警报通过 ARIA live regions 与适当 role 向屏幕阅读器播报。
- Make tabs keyboard navigable(Medium):Tab 组件实现 ARIA tabs 模式。
- Manage focus during dynamic interactions(High):在模态框、页面过渡与内容更新等动态交互中程序化管理焦点。
- Match lang and xml:lang attributes(Medium):html 元素上的
lang与xml:lang属性必须一致。 - Meet minimum color contrast ratios(High):文本与背景颜色必须具有足够对比度。
- Place list items within list containers(Medium):
li元素必须是列表容器(ul、ol、menu)的直接子元素。 - Prevent data loss from session timeouts(High):会话到期前警告用户,允许适当延长并可在不丢失已输入数据的情况下重新认证或恢复工作。
- Prevent seizure-triggering flashing content(Critical):内容每秒闪烁不超过三次,防止光敏性癫痫用户发作。
- Provide accessible authentication methods(High):认证流程避免不必要的认知测试,支持密码管理器、粘贴、OTP 自动填充与 passkey 等辅助机制。
- Provide accessible names for all interactive elements(High):检查交互元素具有可访问名称。
- Provide accessible names for ARIA command elements(Medium):检查 button、link 等命令元素具有可访问名称。
- Provide accessible names for buttons(Critical):所有按钮必须具有可识别、有描述性的可访问名称。
- Provide accessible names for meter elements(Medium):检查 meter 元素具有可访问名称。
- Provide accessible names for progress bars(Medium):检查 progressbar 元素具有可访问名称。
- Provide accessible names for select elements(Medium):所有
<select>元素必须有关联标签或可访问名称。 - Provide accessible names for toggle fields(Medium):检查切换字段(checkbox、radio、switch)具有可访问名称。
- Provide accessible names for tooltips(Medium):检查 tooltip 元素具有可访问名称。
- Provide accessible names for tree items(Medium):所有
role="treeitem"元素必须有描述性可访问名称。 - Provide alt text for image buttons(Critical):
type='image'的 input 元素必须有描述性alt属性。 - Provide alternative text for objects(Medium):
<object>元素必须包含替代内容。 - Provide alternatives to parallax effects(Medium):视差滚动效果有减少动画的替代方案或可被用户禁用。
- Provide audio descriptions for video(Medium):包含重要视觉内容的视频应包括旁白形式的音频描述。
- Provide captions for video content(High):预录视频必须有同步字幕,直播视频必须有实时字幕(WCAG 2.1 SC 1.2.2 与 SC 1.2.4)。
- Provide instant anchor scroll option(Low):锚点链接的平滑滚动动画尊重动效偏好或提供即时替代。
- Provide sufficient touch target size(Medium):交互元素必须有足够大的触摸目标。
- Provide titles for iframes and frames(Medium):iframe 与 frame 必须有
title属性描述其内容。 - Remove focusable elements from aria-hidden containers(Medium):确保
aria-hidden元素内不含可聚焦内容,避免"幽灵"焦点。 - Respect reduced motion preferences(High):动画尊重用户动效偏好,避免触发癫痫的闪烁并为过度动效提供警告。
- Support both portrait and landscape orientation(High):内容与功能在横竖屏均可用,除非特定方向是活动的本质需求。
- Support content reflow at 400% zoom(Critical):放大到 400% 时内容可回流,不要求水平滚动或丢失功能。
- Support text resizing to 200%(High):文本可通过浏览器设置放大到 200% 而不丢失内容或功能。
- Test with screen readers(High):必须用真实屏幕阅读器软件(NVDA、JAWS、VoiceOver、TalkBack)测试播报、焦点顺序与组件行为。
- Use a single label for each form field(Medium):每个表单字段恰好关联一个
<label>元素。 - Use appropriate tabindex values(Medium):检查
tabindex值是否恰当。 - Use correct definition list structure(Medium):定义列表(
<dl>)只能包含合法的<dt>与<dd>元素。 - Use correct list structure(Medium):列表(ul、ol)只能包含
li元素。 - Use descriptive link text(High):链接文本清晰描述目的地或用途,不依赖周围上下文。
- Use exactly one main landmark(Medium):每个页面有且仅有一个 main 地标。
- Use inclusive language(Medium):内容使用包容、非歧视的语言。
- Use landmark regions correctly(Medium):正确的地标区域(main、nav、footer)帮助用户高效导航。
- Use logical heading hierarchy(Critical):标题遵循从 h1 到 h6 的顺序结构,不跳级。
- Use navigation landmark regions(High):页面导航使用带正确 ARIA 标签的 nav 元素以区分多个导航区域。
- Use only allowed ARIA attributes for each role(Medium):检查元素上的 ARIA 属性是否被允许,确保可访问性树有效。
- Use semantic list elements(Medium):相关项目组使用 ul、ol 或 dl,让屏幕阅读器播报列表上下文与项目数量。
- Use semantic table markup for screen readers(Medium):数据表使用带表头、标题与 scope 属性的正确语义标记。
- Use unique IDs for active elements(High):所有可聚焦或活跃元素必须有唯一 ID。
- Use unique IDs for ARIA references(Medium):被 ARIA 属性引用的 ID 必须唯一。
- Use valid ARIA role values(Medium):检查 ARIA role 值是否合法。
- Use valid values for ARIA attributes(Medium):检查 ARIA 属性值是否合法。
- Wrap definition items in a definition list(Medium):描述术语(
<dt>)与详情(<dd>)必须包含在<dl>内。 - Write in plain language(Medium):使用清晰、简单、易于认知障碍用户与非母语者理解的语言。
SEO(94 条)
- 4XX Pages in Sitemap(High):检查 sitemap 中返回 4XX 状态码的 URL。
- Add a favicon to every page(Medium):检查 favicon 存在性与 link 元素配置。
- Add disclaimers to sensitive content(Medium):检查医疗、法律、金融与联盟页面等敏感内容类型的适当免责声明。
- Add FAQPage schema markup(Medium):校验问答内容的 FAQPage JSON-LD 结构化数据。
- Add internal links to key pages(Medium):校验关键页面获得足够的站内链接。
- Add internal links to orphan pages(Medium):检测没有任何站内链接指向的孤页。
- Add LocalBusiness schema markup(Medium):校验本地 SEO 的 LocalBusiness schema。
- Add Organization schema markup(Medium):校验品牌形象的 Organization schema。
- Add outgoing links to dead-end pages(Medium):无站外链接的页面会困住用户与爬虫。
- Add Product schema markup(Medium):校验电商 Product schema。
- Add relevant external links(Medium):校验页面在适当位置包含指向权威外部来源的外链。
- Add Review schema markup(Medium):在商品、服务与商家页面校验 Review 与 AggregateRating schema 以启用星级富结果。
- Add share buttons to content pages(Low):检查文章、博客等可分享内容页面的社交分享按钮。
- Add structured data markup(High):为富搜索结果实现 Schema.org 结构化数据(JSON-LD)。
- Add Twitter Card meta tags(Medium):校验 Twitter(X)Card meta 标签。
- Add VideoObject schema to video pages(Medium):检查含视频页面的 VideoObject 结构化数据。
- Audit all noindex pages(Medium):列出并审查所有被阻止索引的页面。
- Audit and refine AI-generated content(Medium):检测并审查疑似 AI 生成的内容以保证质量。
- Avoid conflicting indexability signals(Medium):检测 robots.txt、meta robots、X-Robots-Tag 与 canonical 标签之间的冲突信号。
- Avoid duplicate meta descriptions(Medium):检查站点内重复的 meta description。
- Avoid keyword stuffing(Medium):检测内容、标题或 meta 标签中过度的关键词重复。
- Avoid multi-hop redirect chains(High):检测浪费抓取预算的多跳重定向链。
- Avoid nofollow on internal links(Medium):标记带
rel=nofollow的内部链接。 - Avoid nosnippet on important pages(Medium):检测阻止搜索引擎摘要的页面。
- Avoid redirect chains on canonical URLs(Medium):确保 canonical 标签直接指向最终目标 URL,无中间重定向。
- Avoid thin content on key pages(Medium):检查关键页面内容长度,识别可能在搜索结果中表现不佳的薄内容。
- Check for broken links(High):测试所有链接且无损坏。
- Cite authoritative external sources(Medium):检查对权威外部网站的引用以支持事实主张并建立信任。
- Create a comprehensive Contact page(Medium):检查提供多种联系方式的专门联系页面。
- Create a dedicated About page(Medium):检查有实质内容的专门关于/公司页面。
- Create and submit an XML sitemap(High):在 /sitemap.xml 提供包含所有重要页面的 XML sitemap。
- Display a physical business address(Medium):检查可见的实体地址信息。
- Display clear author bylines(Medium):检查内容页面上可见的作者姓名。
- Do not link from HTTPS to HTTP(Medium):检测从 HTTPS 页面指向 HTTP 目标的链接,触发混合内容警告并丢失排名信号。
- Fix invalid links(Medium):检测页面上格式错误、为空或语法无效的链接。
- Fix malformed HTML structure(Medium):确保 HTML 文档格式正确、标签正确嵌套与闭合。
- Fix or remove broken external links(Medium):检测并解决返回错误码或超时的外链。
- Geo Meta Tags(Medium):检查本地或区域定位的地理 meta 标签。
- Highlight author credentials and expertise(Medium):检查作者简介与资质以建立专业性与信任。
- Identify YMYL content on your site(High):检测受 Google 更高 E-E-A-T 质量标准约束的"Your Money or Your Life"(YMYL)内容。
- Implement comprehensive author markup(Medium):使用结构化数据提供作者机器可读元数据。
- Implement valid Article structured data(High):校验文章使用正确的 Schema.org 属性。
- Implement valid BreadcrumbList schema(Medium):为面包屑导航添加结构化数据。
- Include indexable pages in your sitemap(Medium):检查 XML sitemap 中缺失的 canonical、可索引页面。
- Include keywords in URL slugs(Medium):检查 URL slug 是否包含描述性、与关键词相关的词。
- Keep HTML documents under crawl limits(Medium):对照 Googlebot 抓取限制检查 HTML 文档大小。
- Keep linked PDFs under 60 MB(Medium):对照 Googlebot 60MB 截断限制检查链接 PDF 大小。
- Keep NAP details consistent(Medium):检查站点内名称、地址、电话(NAP)的一致性。
- Keep page titles unique(High):检查
<title>标签在站点所有页面中唯一。 - Keep sitemap URLs on the correct domain(Medium):检查 sitemap 中所有 URL 与 sitemap 本身属于同一域名与协议。
- Keep URLs concise(Medium):检查 URL 长度以优化可抓取性与可用性。
- Keep XML sitemaps valid(High):按 sitemaps.org 协议校验 sitemap XML 结构、URL 限制与编码要求。
- Limit unnecessary URL parameters(Medium):检查过多的 URL 参数。
- Link directly to final destination URLs(Medium):检测重定向 URL 与指向重定向的链接。
- Link to active social profiles(Low):检查指向组织社交媒体资料的链接,帮助搜索引擎将站点与社会实体关联。
- Make content easy for LLMs to parse(Medium):分析 LLM 解析与理解内容的难易程度。
- Make important pages indexable(Medium):识别被 noindex、robots.txt 或其他指令阻止索引的重要页面。
- Meta Tags in Body(High):检测错误放置在 body 中的 meta 标签。
- MIME Type Validation(Medium):检测 Content-Type 头与文件扩展名不匹配。
- Noindex in Sitemap(High):检查 sitemap 中列出的 noindex 页面。
- OG Image Size(Medium):检查 og:image 是否符合推荐尺寸(1200x630)。
- OG URL Match(Medium):检查 og:url 是否与 canonical URL 匹配。
- Open Graph Tags(Medium):校验社交分享的 Open Graph meta 标签。
- Optimize article link density(Medium):确保文章内链与外链相对其长度保持健康平衡。
- Provide clear affiliate disclosures(Medium):检查联盟与赞助内容披露以保持透明度。
- Publish a robots.txt file(High):检查 robots.txt 是否存在于根目录、可访问且包含有效指令。
- Publish an editorial policy page(Medium):检查展示站点级可信度的编辑与内容政策页面。
- Publish high-quality content(High):基于 LLM 的 SEO 内容质量分析。
- Publish llms.txt for documentation-heavy sites(Medium):提供可选的 llms.txt 索引,将 AI 工具指向高价值文档页面。
- Resolve internal broken links(High):检测并修复返回 404 或 5xx 的内部链接。
- Robots Meta Conflict(High):检测被 robots.txt 阻止且同时携带 noindex meta 标签的页面(指令永远不被读取的悖论)。
- Schema + Noindex Conflict(High):检测携带富结果 schema 标记但被 noindex 或 robots.txt 阻止索引的页面。
- Service Area Pages(Medium):检查服务于多个地理区域的企业的服务区域或位置页面结构。
- Set canonical URLs for all pages(High):页面存在 canonical URL 标签以防重复内容问题。
- Set robots meta directives correctly(High):检查 head 中 robots meta 标签的索引指令合法性。
- Show content freshness signals(Medium):检查 last-modified 与 published date 信号。
- Show published and updated dates(Medium):检查内容页面的发布与修改日期。
- Show trust signals on key pages(Medium):检查高转化页面的信任徽章、认证、客户标志、推荐语与社会证明。
- Sync HTML canonical tags and Link headers(Medium):确保 HTML
rel="canonical"与 HTTP Link canonical 头一致。 - Tel & Mailto Links(Medium):校验电话号码使用
tel:协议、邮箱使用mailto:协议。 - URL Special Characters(Medium):检查 URL 路径中可能导致抓取、解析或规范化问题的特殊字符。
- URL Stop Words(Low):标记 URL slug 中增加长度但不提升关键词相关性的常见停用词。
- Use a single descriptive H1(Medium):校验每个页面恰好一个包含描述性、关键词相关标题的 H1。
- Use canonicals on paginated pages(Medium):检查分页页面的正确 canonical。
- Use descriptive anchor text(Medium):检查描述性、富含关键词的锚文本。
- Use hyphens in URLs(Medium):检查 URL slug 使用连字符而非下划线或空格作为分词符。
- Use lowercase URLs(Medium):检查 URL 是否为小写。
- Use trailing slashes consistently(Medium):检查所有 URL 尾斜杠使用一致,避免重复内容与规范化问题。
- Use valid JSON-LD structured data(Medium):校验 JSON-LD 结构化数据的语法正确性、必需属性与 schema.org 合规性。
- Weak Internal Links(Medium):检测被极少 dofollow 内部链接指向的页面,表明链接权益分配与可发现性差。
- WebSite Search Schema(Low):检查带 SearchAction 的 WebSite schema 以启用 Google 的 Sitelinks Searchbox。
- Write a descriptive page title(High):校验页面标题的存在与长度。
- Write a meta description for each page(High):校验 meta description 的存在与长度。
- Write at a clear reading level(Medium):使用 Flesch-Kincaid 分析内容可读性。
Security(22 条)
- Adblock Element Hiding(Low):检查会被常见广告拦截器隐藏的 HTML 元素与 CSS 类。
- Audit dependencies for known vulnerabilities(High):使用自动化工具定期扫描依赖的已知安全漏洞并在部署前修复关键发现。
- Avoid mixed content on HTTPS pages(High):HTTPS 页面通过 HTTP 加载资源即产生混合内容。
- Blocked Tracking Links(Low):指向已知追踪或广告域名的链接与资源可能被广告拦截器阻止。
- External Link Security(Medium):使用
target='_blank'新标签页打开的链接必须包含rel='noopener noreferrer'。 - Implement a content security policy(High):实施内容安全策略(CSP)以防 XSS 并控制资源加载。
- Leaked Environment Variables(Critical):检查 HTML 源码、JS 包或客户端可访问文件中暴露的 API 密钥、令牌、密码等机密。
- Link to your terms of service in the footer(Medium):提供服务的企业应发布服务条款并在每个页面链接。
- Prevent stack trace exposure in production error responses(High):生产错误响应绝不包含堆栈跟踪、内部路径、框架内部细节(OWASP A09)。
- Protect public forms with CAPTCHA(Medium):接受未认证用户输入的公开表单必须包含机器人保护。
- Redirect HTTP to HTTPS(Critical):所有 HTTP 请求必须永久重定向(301)到 HTTPS。
- Secure password input fields(High):密码字段实现正确 autocomplete、显示/隐藏切换与强度指示器等最佳实践。
- Serve all pages over HTTPS(Critical):站点每个页面与资源都必须通过 HTTPS 交付。
- Set a Permissions-Policy header(Medium):Permissions-Policy 头限制页面或嵌入 iframe 可用的浏览器功能(摄像头、麦克风、地理位置等)。
- Set a Referrer-Policy header(Medium):Referrer-Policy 头控制从站点跳转时发送的 referrer 信息量。
- Set an HSTS header(High):Strict-Transport-Security 响应头告诉浏览器始终对域名使用 HTTPS,防止协议降级攻击与 Cookie 劫持。
- Set an X-Frame-Options header(High):X-Frame-Options 头控制页面能否被嵌入 iframe,防止点击劫持。
- Set Secure, HttpOnly, and SameSite flags on session cookies(High):所有会话与认证 Cookie 带 Secure、HttpOnly 与恰当的 SameSite 标志。
- Set X-Content-Type-Options: nosniff(High):
X-Content-Type-Options: nosniff阻止浏览器对响应进行 MIME 嗅探。 - Store authentication tokens securely(High):敏感认证令牌存储在 httpOnly Cookie 而非 localStorage/sessionStorage(OWASP A07)。
- Submit forms over HTTPS(Critical):所有 HTML 表单 action 必须指向 HTTPS URL。
- Use COOP, COEP, and CORP for cross-origin isolation when needed(Medium):敏感或高能力应用有意使用 COOP、COEP、CORP,审计第三方嵌入并在依赖前验证跨源隔离。
Images(25 条)
- Compress images without quality loss(High):压缩所有图片且不显著损失质量。
- Fix broken images(High):无图片返回 404 或显示破图图标。
- Handle image loading errors gracefully(Low):用回退图片或占位内容优雅处理破图。
- Implement responsive images with srcset(High):图片使用
srcset与sizes属性跨设备响应式交付。 - Keep image file sizes within recommended limits(High):单张图片压缩到合理大小以避免浪费带宽。
- Lazy load offscreen images(High):首屏以下图片使用
loading="lazy"延迟下载。 - Manage inline SVG size and complexity(Medium):将内联在 HTML 中的大型或复杂 SVG 提取到外部文件或组件。
- Optimise images for faster loading(High):部署前压缩并剥离元数据的图片。
- Optimize all images for web(High):使用恰当的格式、压缩与现代化技术优化图片。
- Optimize SVG files(Medium):用 SVGO 优化 SVG 文件以移除元数据并减小体积。
- Prioritize loading critical images(High):Hero 与首屏图片以高 fetch 优先级预加载以改善 LCP。
- Provide meaningful alt text for images(Critical):每张信息型图片有描述性
alt属性;装饰性图片用alt=""。 - Serve images at the correct display size(High):图片不能显著大于其显示尺寸。
- Serve images from a CDN(High):图片由带自动优化、缩放与格式转换的 CDN 提供。
- Set explicit width and height on images(High):所有
<img>元素有显式 width/height 属性以预留空间、防止布局偏移。 - Support high-DPI retina displays(Medium):为视网膜与高 DPI 显示提供 2x、3x 高清图。
- Use
<figure>and<figcaption>for image captions(Medium):带可见说明的图片包裹在<figure>中并含<figcaption>子元素。 - Use
<picture>with an<img>fallback(High):每个<picture>元素以必需的<img>作为最后一个子元素。 - Use AVIF format for modern browsers(Medium):图片支持 AVIF 格式并带正确的浏览器回退。
- Use descriptive image filenames(Low):图片文件名描述性、人类可读,使用小写字母、连字符分词。
- Use image sprites where appropriate(Low):小图片与图标使用雪碧图或 SVG 以减少 HTTP 请求。
- Use modern image formats (WebP, AVIF)(High):浏览器支持时以 WebP 或 AVIF 替代旧式 JPEG/PNG。
- Use progressive JPEG encoding(Low):JPEG 图片使用渐进式格式以获得更好的感知加载性能。
- Use srcset for responsive images(High):宽于 100px 的图片使用
srcset提供多分辨率变体。 - Use WebP format with fallbacks(High):以 WebP 格式提供图片并为旧浏览器回退。
Testing(13 条)
- Enforce performance budgets in CI(Medium):定义可衡量的性能阈值(打包体积、Lighthouse 分数、Core Web Vitals)并在超限时让 CI 构建失败。
- Follow mocking best practices(Medium):策略性使用 mock 隔离被测单元,避免过度 mock。
- Implement consumer-driven contract testing for API boundaries(Medium):消费者驱动契约测试(Pact)定义并验证前端消费者与后端提供方之间的 API 契约。
- Implement end-to-end testing(High):用 Playwright 或 Cypress 等 E2E 框架测试关键用户旅程。
- Include accessibility testing(High):用 axe-core、jest-axe 或 Playwright 的无障碍测试自动执行。
- Integrate real-time error monitoring in production(High):生产环境的实时错误监控服务捕获、分组并告警未处理异常与 Promise 拒绝。
- Maintain test coverage thresholds(Medium):设定并强制最低代码覆盖率阈值。
- Test across all major browsers(High):网站在主流浏览器(Chrome、Firefox、Safari、Edge)正常工作。
- Test on real mobile devices and viewports(High):在真实移动设备与 DevTools 设备模拟中验证应用。
- Use mutation testing to measure how well tests detect bugs(Medium):在关键业务逻辑上运行 Stryker 变异测试。
- Use visual regression testing(Medium):截图组件与页面并与批准的基线自动对比。
- Write integration tests for key workflows(High):测试多个代码单元如何协同工作。
- Write unit tests(High):关键功能有覆盖率良好的单元测试。
Privacy(5 条)
- Avoid third-party cookies(Medium):外部域设置的第三方 Cookie 在用户不知情的情况下跨站追踪,现代浏览器正逐步淘汰它们,GDPR 与 CCPA 要求设置前征得同意。
- Collect only the minimum personal data necessary(Medium):仅收集目的所严格必需的数据,符合 GDPR 第 5(1)(c) 条数据最小化原则。
- Implement a user-facing data deletion mechanism(Medium):为用户提供清晰的数据删除请求方式,履行 GDPR 第 17 条(被遗忘权)。
- Link to your privacy policy in the footer(High):收集个人数据的网站必须发布隐私政策并显著链接(GDPR、CCPA 等法律要求)。
- Show a cookie consent notice(High):设置非必需 Cookie 的网站必须在放置 Cookie 前获得事先知情同意。
Internationalization(5 条)
- Add hreflang tags for multilingual sites(Medium):hreflang 标签指示多语言站点的语言与区域变体。
- Design UI components to accommodate text expansion from translation(Medium):布局使用弹性尺寸,使翻译文本(可比英文长 30–50%)不溢出、不裁剪、不破坏 UI。
- Handle plural forms with Intl.PluralRules or ICU MessageFormat(Medium):用
Intl.PluralRules或 ICU 感知的 i18n 库为每种语言选择正确的语法复数类别。 - Use Intl APIs for currency, number, and date formatting(Medium):使用浏览器内置的
Intl.NumberFormat与Intl.DateTimeFormat格式化货币、数字与日期。 - Use locale-neutral images and provide cultural overrides when needed(Low):默认使用抽象、文化中立的图标与插画,仅当视觉内容携带跨区域含义差异时提供地区变体。
四档优先级体系:Critical / High / Medium / Low
每条规则都有一个优先级,类型定义在 packages/rules/src/types.ts:
export type FrontendChecklistPriority = 'critical' | 'high' | 'medium' | 'low'
- Critical:安全与合规底线(如 Serve all pages over HTTPS、Redirect HTTP to HTTPS、Leaked Environment Variables、Do not use aria-hidden on the body、Provide meaningful alt text),一旦缺失直接威胁安全、合规或基础可用性。
- High:影响用户体验、性能指标或排名信号的常规硬性要求(如 LCP < 2.5s、Enable browser caching、CSP、unique page titles)。
- Medium:最佳实践与质量打磨(如 favicons、print stylesheet、sprite、hreflang)。
- Low:前沿特性或锦上添花(如
@property、:has()、View Transitions、Speculation Rules)。
目录生成时,优先级通过 Markdown 图片引用徽章展示(见 generate-readme.ts):
[critical_img]: apps/web/public/priority/critical.svg
[high_img]: apps/web/public/priority/high.svg
[medium_img]: apps/web/public/priority/medium.svg
[low_img]: apps/web/public/priority/low.svg
徽章图片本体位于 apps/web/public/priority/。该优先级不仅是展示信息,还被下游工具消费——例如审计引擎与 MCP 服务会依据优先级决定问题的上报等级与修复建议的强调程度。
解剖一条规则:frontmatter 结构深度解析
目录中的每一行都源自单个 .mdx 文件的 frontmatter。以安全分类的 https.mdx 为例,一条完整规则包含丰富的元数据字段:
| 字段 | 含义 | 示例(https 规则) |
|---|---|---|
title | 规则标题 | Serve all pages over HTTPS |
description | 目录中展示的一句话描述 | Every page and resource must be delivered over HTTPS |
categories | 所属分类数组,首项为目录归属 | [security] |
subcategory | 子分类 | transport |
priority | 优先级 | critical |
difficulty | 实施难度 | beginner |
estimatedTime | 预估实施分钟数 | 30 |
tldr | 要点速览列表 | HTTP 必须 301 重定向到 HTTPS;证书须覆盖全部主机名等 |
whyItMatters | 为何重要(供 AI 上下文理解) | 明文 HTTP 让 ISP、Wi-Fi 运营者与中间人可读取密码与会话令牌 |
aiContext | AI 何时使用该规则 | 审计网站是否全程 HTTPS 时 |
prompts | 结构化提示词:check / fix / explain / codeReview | 如何检查、如何修复、如何解释、如何代码评审 |
sources | 权威参考资料(MDN、web.dev、OWASP 等,含 role 与 authority) | MDN transport security、web.dev why-https-matters、OWASP 传输层保护速查表 |
resources | 实用工具/指南 | Mozilla Observatory |
relatedRules | 关联规则及其关联原因 | http-to-https、form-https、mixed-content、referrer-policy |
正文部分则承载可执行的实战内容:Let's Encrypt/Certbot 命令、Nginx/Apache 的 301 重定向配置、Cloudflare 的 Always Use HTTPS 设置、需要 HTTPS 的现代 API 对照表、常见坑位表格(过期证书、www 缺失、302 重定向、仅登录页启用 HTTPS)以及验证方法(自动化探测 + 生产环境人工核对)。
prompts 字段是这套体系区别于普通文档的关键设计:它把每条规则转译成 AI Agent 可执行的 check(审计)、fix(修复)、explain(解释)、codeReview(代码评审)四类操作指令,配合 aiContext 与 sources,让 LLM 在审计场景中"拿到规则即可行动"。这也是仓库中 packages/mcp 与 skills 体系能批量消费规则的原因。
规则目录的消费场景:站点、Agent 与检索
rules-catalog.md 不是孤立的文档,它与仓库的多条消费链路相连:
- Web 应用:路由构造器定义在 packages/config/src/routes.ts(
routeRule(category, slug)生成/rules/{category}/{slug}),站点页面按分类与 slug 渲染单条规则详情;生成脚本通过absoluteRuleUrl生成指向站点的链接。 - Agent / LLM:规则的
prompts、aiContext、tldr、sources字段专为 Agent 检索与执行设计,规则目录充当 Agent 的"规则检索表";仓库还内置 packages/mcp 服务,使外部工具能按规则查询与调用。 - 内容资产:12 个 checklists 与 guides 复用规则体系;
llms.txt规则则指导文档型站点为 AI 工具提供可解析索引。
如何高效阅读与使用这份目录
- 按分类速览:从 Quick links 跳转到目标分类,先读分类描述再浏览清单;Accessibility 与 SEO 体量最大,适合按子主题(ARIA、structured data、headers)分批消化。
- 按优先级排优先级:优先处理 Critical 与 High 规则(安全、合规、核心性能指标),Medium/Low 作为迭代优化项——这与规则本身的
estimatedTime、difficulty字段结合可做工作量预估。 - 以单条规则为最小单元深入:在 packages/content/rules/en/ 对应分类目录中找到
.mdx文件,阅读正文的代码示例、配置片段与验证清单;利用relatedRules追踪同主题关联规则(如 https → http-to-https → form-https → mixed-content)。 - 让 Agent 直接消费:将单条规则的
prompts与aiContext提供给 LLM,即可获得"检查 → 修复 → 解释 → 代码评审"的完整闭环操作指引。 - 保持目录同步:若新增或修改规则,运行
pnpm generate:readme重新生成 rules-catalog.md 与根 README 目录块,而不是手工编辑生成文件。
小结
rules-catalog.md 是一份"规则即数据"思想的集中体现:385 条规则以结构化 frontmatter 存储,经 generate-readme.ts 自动汇编为人类可读目录,同时其 prompts、aiContext 等字段让它天然可被 Agent 与 LLM 检索执行。理解这份目录的分类骨架(11 类)、优先级体系(四级)与单条规则结构(frontmatter + 正文 + 验证),你就能把整个规则库当作可编程的前端质量基础设施来使用——无论是人工逐条核对,还是交给自动化审计与 AI 助手批量执行。
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



