质量保证

相关源文件

• .github/workflows/readme-check.yml
• .husky/pre-push
• .markdownlint.json
• lychee.toml
• package.json

目的与范围

本文档概述了在 Front-End Checklist 存储库中实施的质量保证流程。它描述了用于维护项目文档（特别是包含实际清单项目的 README.md 文件）的一致性、格式标准和链接有效性的工具、工作流和配置。

有关特定链接验证技术的更多信息，请参阅 链接验证。有关如何处理不活跃问题和拉取请求的更多信息，请参阅 陈旧问题管理。

质量保证工具概述

Front-End Checklist 项目采用多种工具来确保文档质量

工具	目的	配置
Prettier	代码格式化	默认配置
Markdownlint	Markdown 语法检查	.markdownlint.json 中的自定义规则
Husky	用于推送前验证的 Git 钩子	在 .husky/pre-push 中定义的钩子
GitHub Actions	CI/CD 流水线验证	.github/workflows/readme-check.yml 中的工作流
Lychee	链接检查	lychee.toml 中的设置

来源

• package.json1-28
• .markdownlint.json1-6
• .husky/pre-push1-2
• .github/workflows/readme-check.yml1-40
• lychee.toml1-21

质量保证架构

下图展示了不同的质量保证工具如何与代码库集成

来源

• package.json5-9
• .github/workflows/readme-check.yml1-40
• .husky/pre-push1-2
• .markdownlint.json1-6
• lychee.toml1-21

本地开发 QA 流程

在更改可以推送到存储库之前，Front-End Checklist 会通过 Git 钩子实施本地质量检查

推送前钩子

Husky 推送前钩子会在允许代码推送到远程存储库之前自动运行

pnpm format:fix

这个简单的命令执行 package.json 中定义的 format:fix 脚本，该脚本执行两个操作

1. 使用 Prettier 格式化 README.md 文件
2. 使用 Markdownlint 检查 README.md 文件

如果发现格式问题，Prettier 会自动修复它们。如果识别出语法问题且无法自动修复，推送将失败，开发人员必须手动解决这些问题。

来源

• .husky/pre-push1-2
• package.json7

NPM 脚本

package.json 中以下 NPM 脚本支持质量保证

脚本	命令	目的
format:check	prettier --check README.md	验证 README.md 是否格式正确，但不进行更改
format:fix	prettier --write README.md && markdownlint README.md	自动格式化 README.md，然后检查 Markdown 语法问题
prepare	husky || true	在包安装期间设置 Husky Git 钩子

来源

• package.json5-9

CI/CD 质量保证

当通过拉取请求提交对 README.md 的更改时，会执行自动 CI/CD 检查

Readme Check 工作流程

.github/workflows/readme-check.yml 中定义的 GitHub Actions 工作流会在修改 README.md 的拉取请求上触发

工作流执行两项关键检查

1. 使用 Prettier 进行格式检查，以确保 README 保持一致的格式
2. 使用 Lychee 进行链接验证，以验证 README 中的所有链接是否有效

如果任何一项检查失败，则在问题解决之前，该拉取请求将无法合并。

来源

• .github/workflows/readme-check.yml1-40

配置详情

Markdownlint 配置

.markdownlint.json 文件通过禁用特定规则来配置 Markdownlint，否则这些规则会标记 README.md 文件中的问题

鉴于 Front-End Checklist 的结构和内容要求，这些例外是必要的。

来源

• .markdownlint.json1-6

Lychee 链接检查器配置

.markdownlint.json 文件包含 Lychee 链接检查器的详细配置

类别	设置	值	目的
显示	verbose	"info"	设置日志级别
	output	"./lychee-out.md"	定义输出位置
缓存	cache	true	启用缓存
	max_cache_age	"2d"	将缓存有效性设置为 2 天
运行时	max_concurrency	14	限制并发请求
请求	user_agent	"curl/7.83.1"	设置请求用户代理
	timeout	20	设置请求超时（秒）
	accept	["200", "429", "403"]	定义可接受的 HTTP 状态码
	scheme	["https"]	仅检查 HTTPS 链接
排除项	base	"https://github.com/thedaviddias/Front-End-Checklist/"	定义基本 URL
	exclude	["https://caniuse.cn"]	跳过检查特定 URL

该配置旨在处理链接检查中的常见问题，例如速率限制（429 响应）和访问限制（403 响应）。

来源

• lychee.toml1-21

端到端 QA 工作流

下图说明了从本地开发到拉取请求审查的完整质量保证工作流

此工作流确保

1. 代码在离开开发人员的机器之前已正确格式化
2. 拉取请求经过额外的验证，以捕获本地遗漏的任何问题
3. README.md 文件保持一致的格式并包含有效的链接

来源

• package.json5-9
• .husky/pre-push1-2
• .github/workflows/readme-check.yml1-40

故障排除常见 QA 问题

问题	可能原因	解决方案
推送前钩子失败	README.md 中的格式或语法问题	手动运行 pnpm format:fix 以查看和修复错误
GitHub Actions 格式检查失败	README.md 格式不符合 Prettier 标准	在本地运行 pnpm format:fix，提交并推送更改
链接验证失败	README.md 中的无效链接	检查 GitHub Actions 输出以识别有问题的链接并更新它们
Husky 钩子未运行	钩子未正确安装	运行 pnpm prepare 以重新安装 Husky 钩子

来源

• package.json5-9
• .github/workflows/readme-check.yml1-40

总结

Front-End Checklist 项目实施了一个全面的质量保证系统，专注于维护其核心文档的完整性。通过结合本地开发检查和 CI/CD 验证，该项目确保

1. README.md 文件保持一致的格式
2. 遵循 Markdown 最佳实践
3. 所有链接都保持有效
4. 包含文档更改的拉取请求在合并前经过彻底验证

这种多层方法有助于保持 Front-End Checklist 的高质量，使其成为前端开发人员可靠的资源。