linkrot

linkrot

文档链接检查器，会区分不同的失败类型，而不是把每个错误响应都称为失效链接。相对链接和锚点会根据文件系统进行验证。外部链接则按实际情况分类：正常、失效、已移动、被机器人拦截或错误。来自机器人拦截页的 403 不属于失效链接，linkrot 绝不会将其报告为失效链接。

功能

• 遍历目标目录中的 Markdown 文件（跳过 node_modules、.git 和 dist），或检查单个 Markdown 文件。
• 提取行内链接（包括图片链接）、引用式定义，以及能解析到定义的引用用法。忽略围栏代码块中的链接。不提取正文中的裸 URL 和自动链接。
• 按类别检查每个链接：
  • RELATIVE-FILE：路径部分相对于 Markdown 文件解析。目标不存在时，会产生 DEAD-RELATIVE 发现项（高）。
  • RELATIVE-ANCHOR：文件存在，但锚点 slug 不在目标文件的标题 slug 中。这会产生 ANCHOR-MISSING 发现项（中）。Slug 的生成方式是转为小写、去除标点，并将空格替换为连字符。
  • SAME-FILE-ANCHOR：同一文件中的 #section 这类链接，会根据相同的 ANCHOR-MISSING 规则，对照该文件的标题 slug 进行检查。
  • EXTERNAL：离线模式下，http 和 https 链接会作为 UNCHECKED 信息项报告。它们会计数，但不会导致检查失败。
  • MAILTO 和其他方案会静默跳过，并计入 skipped。

安装

npx @reneturcios/linkrot check .

也可以全局安装：

npm install -g @reneturcios/linkrot

命令行界面

linkrot check [path] [--json]
linkrot mcp
linkrot --version

• check 对路径执行离线检查（默认：当前目录）。当判定结果为 OK 时，退出代码为 0；其他任何判定结果的退出代码均为 1。使用 --json 可获取机器可读报告。
• mcp 通过 stdio 启动 MCP 服务。
• --version 打印版本号。

MCP

MCP 服务提供一个工具：

• check_links，接受 path 参数。它返回与 linkrot check --json 相同的 JSON 报告。

默认离线

离线模式是默认模式，也是随附的默认模式。核心是同步的，不会发起网络请求。

这是有意为之。linkrot 的初衷是：自动抓取经常会遇到机器人拦截页、登录门槛和速率限制。如果检查器抓取每个外部 URL，并将任何非 2xx 响应都视为失效，那么只要网站拦截机器人，它就会把正常页面报告为失效。离线模式完全避免了这种问题：它只验证本地能够验证的内容（相对文件和锚点），并如实将外部链接报告为 UNCHECKED，而不是妄加判断。

链接类别与状态词汇

未来在线模式检查外部 URL 时，每个 HTTP 状态码都只会映射到以下一个类别：

类别	含义
healthy	2xx，以及非永久迁移的 3xx 重定向（例如 302、304、307）
dead	404 或 410：页面已不存在
moved	重定向到新位置。永久重定向（301、308）会使用单独的标签 moved-permanent。
bot-blocked	401、403 或 429：机器人拦截页、身份验证门槛或速率限制返回了响应。页面对人类用户来说可能仍然正常。
error	5xx 及其他情况：检查本身无法获得可信的结果

函数 classifyStatus(status) 实现了此表，并经过单元测试。将 bot-blocked 与 dead 区分开正是此工具的要点：混为一谈会导致每个 Cloudflare 拦截页或登录门槛都被误报为失效链接。

判定规则

• 当没有 DEAD-RELATIVE 和 ANCHOR-MISSING 发现项时，判定结果为 OK。
• 其他情况下，判定结果为 FINDINGS。
• 离线模式下，UNCHECKED 外部链接不会影响判定结果。

报告会统计文件数、链接数、dead、anchorsMissing 和 externalUnchecked，并按类别统计数量：relativeFile、relativeAnchor、sameFileAnchor、external 和 skipped。

限制

• 离线核心功能只检查相对链接和锚点。
• 离线时不会检查外部链接是否可访问。外部链接会标记为 UNCHECKED，绝不会猜测其正常或失效。未来的在线模式将使用上述词汇对其进行分类。
• 提取范围包括行内链接和引用定义（会解析完整和折叠的引用用法）。不会提取快捷引用链接、裸 URL 和自动链接。
• 仅当链接目标为 Markdown 文件时，才会检查锚点。不会验证指向非 Markdown 文件的锚点。
• 标题 slug 遵循简化的 GitHub 规则：转换为小写、去除标点、将空格替换为连字符；重复标题会依次添加 -1、-2 等后缀。

开发

npm install
npm run build
npm test