链接验证

相关源文件

• .github/workflows/links-checker.yml
• .github/workflows/readme-check.yml
• .github/workflows/stale.yml
• .husky/pre-push
• .markdownlint.json
• CONTRIBUTING.md
• lychee.toml

目的与范围

本文档详细介绍了Front-End Checklist存储库中实现的自动化链接验证系统。它涵盖了确保项目文档中的所有链接随着时间的推移保持功能性的工具、配置和工作流程。这对于维护清单的质量和实用性至关重要，该清单包含大量对外部资源的引用。有关更广泛的质量保证流程的信息，请参阅质量保证。

链接验证系统概述

Front-End Checklist通过GitHub Actions工作流程和Lychee链接检查工具使用自动化方法进行链接验证。该系统以两种不同的模式运行，以确保全面的覆盖。

来源： .github/workflows/readme-check.yml .github/workflows/links-checker.yml

Lychee链接检查器

该存储库使用Lychee，一个用Rust编写的快速而准确的链接检查器，通过专用的配置文件进行配置。

配置

在lychee.toml中定义的配置提供了以下设置

类别	设置	值	目的
显示	verbose	info	设置输出详细程度级别
显示	output	./lychee-out.md	将结果存储为Markdown格式
缓存	cache	true	启用链接检查结果的缓存
缓存	max_cache_age	2d	指定缓存有效性期（2天）
运行时	max_concurrency	14	限制并发请求的数量
请求	user_agent	curl/7.83.1	设置请求的用户代理（User-Agent）标头
请求	timeout	20	设置请求超时（秒）
请求	accept	[200, 429, 403]	被视为有效响应的HTTP状态码
请求	scheme	[https]	仅限制检查HTTPS URL
排除项	base	github仓库URL	设置相对链接的基础URL
排除项	exclude	[https://caniuse.cn]	要排除在检查之外的URL

来源： lychee.toml

验证工作流程

拉取请求验证

当一个拉取请求修改README.md文件时，一个GitHub Actions工作流程会自动运行，以验证文档中的所有链接。

该工作流程在readme-check.yml中定义，并包含以下步骤

1. 检出存储库
2. 设置Node.js版本22
3. 设置pnpm版本9
4. 安装依赖项
5. 检查Markdown格式
6. 使用lychee.toml的配置运行Lychee链接检查器
7. 如果任何链接无效，则检查失败

来源： .github/workflows/readme-check.yml

计划验证

为了检测随着时间推移而变得损坏的链接，一个计划好的工作流程每周运行一次

该工作流程在links-checker.yml中定义，并于每周一午夜UTC自动运行。当发现损坏的链接时，它会创建一个GitHub问题，其中包含

1. 清晰的标题（“链接检查器报告”）
2. 用于分类的标签（“report”、“automated issue”）
3. 一份详细报告，显示哪些链接已损坏以及原因

来源： .github/workflows/links-checker.yml

技术实现

GitHub Actions 集成

两个链接验证工作流程都使用lycheeverse/lychee-action@v2.0.2 GitHub Action来执行链接检查。此操作

1. 使用工作流程中的参数运行Lychee命令
2. 扫描指定的文件的（README.md）
3. 使用lychee.toml中的配置
4. 根据链接的有效性返回成功或失败状态

错误处理与报告

两个工作流程之间的错误处理方式不同

1. Pull Request Checks: 导致GitHub检查失败，阻止合并，直到修复
2. Scheduled Checks: 创建一个包含详细报告的GitHub问题，允许异步修复

生成的报告（lychee-out.md）包含

• 哪些链接已损坏
• 遇到的具体错误（超时、404等）
• README.md文件中损坏链接的位置

与其他质量流程的集成

链接验证系统与其他质量保证流程协同工作

1. Markdown Linting: 确保格式一致性（在.markdownlint.json中定义）
2. Pre-push Hooks: 在使用Husky推送之前格式化文件（在.husky/pre-push中定义）
3. Stale Issue Management: 保持存储库的整洁（请参阅Stale Issue Management）

来源： .markdownlint.json .husky/pre-push

链接验证的贡献指南

在为Front-End Checklist做贡献时，以下最佳实践有助于维护链接的有效性

1. 在提交拉取请求之前，手动验证所有链接
2. 尽可能使用永久链接或内容的存档版本
3. 及时修复PR检查期间标记的任何链接验证问题
4. 在报告链接问题时，提供问题的上下文

有关为项目做贡献的更多详细信息，请参阅为项目做贡献。

来源： CONTRIBUTING.md

总结

Front-End Checklist存储库中的链接验证系统通过以下方式提供了强大的机制来确保文档质量

1. 在拉取请求期间进行自动检查，以防止引入损坏的链接
2. 定期计划检查，以识别随时间推移而损坏的链接
3. 详细的报告，以便快速修复
4. 用于处理特殊情况的配置选项

该系统有助于保持存储库的高质量和实用性，作为前端开发社区的参考。