链接检查

本项目在 CI 构建过程中自动对新增和修改的内容进行链接检查。

工作原理¶

链接检查系统会自动执行以下操作：

检测变更文件：使用 git diff 查找新增或修改的 Markdown 文件
提取链接：识别普通链接 [文本](url) 和图片链接 ![alt](url)
验证链接：
外部链接：通过 HTTP HEAD 请求验证可达性
内部链接：检查引用的文件是否存在于本地磁盘
输出摘要：生成详细统计信息并列出所有失效链接

功能特性¶

📄 逐文件分析，仅检查变更内容
🌐 外部链接验证，支持超时和错误处理
📁 内部链接校验，对比本地文件系统
🖼️ 图片链接检查，支持外部和内部图片
📊 全面统计与摘要报告
❌ 失效链接详情，包含具体错误信息
⚡ 重复 URL 去重，避免重复检查

使用方法¶

CI 自动运行¶

在每次构建时，链接检查会通过 GitHub Actions 自动运行：

- name: Run tests
  run: npm test
  continue-on-error: true

- name: Run link check summary
  run: node test/link-check-summary.js
  continue-on-error: true

手动测试¶

# 运行完整测试套件（包含链接检查）
npm test

# 仅运行链接检查及摘要
npm run link-check

示例输出¶

📝 Link Check Summary
==================================================
📄 Files checked: 2

🔍 Checking: content/zh/blog/new-post.md
   📊 Links: 3 external, 2 internal, 1 images

🔍 Checking: content/en/docs/guide.md
   📊 Links: 1 external, 0 internal, 0 images

📊 Summary Statistics
------------------------------
🔗 Total links found: 6
🖼️  Total images found: 1
🌐 External links: 4
📁 Internal links: 2
❌ Broken external links: 1
❌ Broken internal links: 0

🚫 Broken External Links
------------------------------
🔗 content/zh/blog/new-post.md: https://example-broken-link.com
   Status: 404

✅ All internal links are valid!

❌ Found 1 broken link(s) in total.
==================================================

配置说明¶

超时设置¶

外部链接默认超时时间为 10 秒。可在 test/link-check-summary.js 中修改：

const req = lib.request(url, { method: 'HEAD', timeout: 10000 }, (res) => {

忽略链接¶

根路径链接（以 / 开头）会自动跳过，由 Hugo 处理
忽略特定域名：可将域名添加到 scripts/ignore-urls.txt，用于 htmlproofer 检查

检查的链接类型¶

✅ 外部 HTTP/HTTPS 链接
✅ 内部相对路径链接
✅ 图片引用（外部和内部）
❌ 根路径链接（跳过，由 Hugo 处理）
❌ 锚点链接（暂不校验）

错误处理¶

系统支持多种错误场景：

网络超时：外部请求超时为 10 秒
DNS 解析失败：报告 EAI_AGAIN 错误
HTTP 错误：报告状态码（如 404、500 等）
文件缺失：内部链接检查本地文件是否存在
URL 格式错误：解析异常时自动跳过

贡献指南¶

如需新增链接检查功能：

更新 test/link-check-summary.js 核心逻辑
保持与现有 test/content.test.js 兼容
使用有效和失效链接进行测试
更新本说明文档

链接检查

工作原理¶

功能特性¶

使用方法¶

CI 自动运行¶

手动测试¶

示例输出¶

配置说明¶

超时设置¶

忽略链接¶

检查的链接类型¶

错误处理¶

贡献指南¶

相关文件¶