查找死链（失效链接）

死链（失效链接）是指网页中无法连接的链接。这些链接可能对 SEO 和安全性产生负面影响。本工具可轻松识别并修改此类链接。

正在寻找 v1（Ruby gem）版本？ 它现在位于 legacy/v1 分支，并继续发布 deadfinder gem，仅用于错误修复和安全更新。main 分支承载 Crystal 重写版本（v2+）。

安装

Homebrew

brew install deadfinder
# https://formulae.brew.sh/formula/deadfinder

Docker

docker run ghcr.io/hahwul/deadfinder:latest deadfinder url https://example.com

预编译二进制

从最新发布页面下载对应平台的压缩包，解压后将 deadfinder 放入 PATH 环境变量中。

Nix

nix run github:hahwul/deadfinder
nix profile install github:hahwul/deadfinder
nix develop github:hahwul/deadfinder

从源码构建

需要 Crystal >= 1.19.1 和 cmake（用于 lexbor HTML 解析器的安装后脚本；若缺少该工具，shards install 会报错 'cmake': No such file or directory）。

# macOS
brew install crystal cmake

# Debian / Ubuntu
sudo apt install crystal cmake

shards install
crystal build src/cli_main.cr -o deadfinder --release
# 或：直接构建

使用方式

命令行

deadfinder sitemap https://www.hahwul.com/sitemap.xml

GitHub Action

请锁定具体的发布标签。@latest 不是有效的 Actions 引用。

steps:
- name: 运行 DeadFinder
  uses: hahwul/deadfinder@v2       # 跟踪最新的 2.x 版本——为更严格的可复现性，建议锁定具体标签（如 @2.0.2）
  id: broken-link
  with:
    command: sitemap           # url / file / sitemap / pipe
    target: https://www.hahwul.com/sitemap.xml
    # timeout: 10
    # concurrency: 50
    # silent: false
    # headers: "X-API-Key: 123444"
    # worker_headers: "User-Agent: Deadfinder Bot"
    # include30x: false
    # user_agent: "Apple"
    # proxy: "http://localhost:8070"
    # proxy_auth: "id:pw"
    # match:  ""
    # ignore: ""
    # coverage: true
    # visualize: report.png

- name: 输出处理
  run: echo '${{ steps.broken-link.outputs.output }}'

如果发现了失效链接并希望自动创建 Issue，请参阅 "自动检测死链" 文章。

用法

Usage: deadfinder <command> [options]

Commands:
  pipe                        从 STDIN 扫描 URL
  file <FILE>                 从文件扫描 URL
  url <URL>                   扫描单个 URL
  sitemap <SITEMAP-URL>       从站点地图扫描 URL
  completion <SHELL>          生成补全脚本（bash/zsh/fish）
  version                     显示版本

Options:
  -r, --include30x                 将 30x 重定向视为死链
  -c, --concurrency=N              并发工作数（默认：50）
  -t, --timeout=N                  超时秒数（默认：10）
  -o, --output=FILE                结果输出文件
  -f, --output_format=FORMAT       输出格式：json, yaml, toml, csv, sarif（默认：json）
  -H, --headers=HEADER             初始请求的自定义 HTTP 头
      --worker_headers=HEADER      工作请求的自定义 HTTP 头
      --user_agent=UA              用户代理字符串
  -p, --proxy=PROXY                代理服务器（HTTP 和 HTTPS CONNECT）
      --proxy_auth=USER:PASS       代理认证
  -m, --match=PATTERN              匹配 URL 模式（正则）
  -i, --ignore=PATTERN             忽略 URL 模式（正则）
  -s, --silent                     静默模式
  -v, --verbose                    详细模式
      --debug                      调试模式
      --limit=N                    限制扫描 URL 数量
      --coverage                   启用覆盖率跟踪与报告
      --visualize=PATH             生成可视化 PNG

模式

# 从 STDIN 扫描 URL（多个 URL）
cat urls.txt | deadfinder pipe

# 从文件扫描 URL
deadfinder file urls.txt

# 扫描单个 URL
deadfinder url https://www.hahwul.com

# 从站点地图扫描 URL
deadfinder sitemap https://www.hahwul.com/sitemap.xml

JSON 处理

deadfinder sitemap https://www.hahwul.com/sitemap.xml -o output.json
cat output.json | jq

{
  "Target URL": [
    "DeadLink URL",
    "DeadLink URL",
    "DeadLink URL"
  ]
}

使用 --coverage 参数：

deadfinder sitemap https://www.hahwul.com/sitemap.xml --coverage -o output.json

{
  "dead_links": {
    "Target URL": ["DeadLink URL 1", "DeadLink URL 2"]
  },
  "coverage": {
    "targets": {
      "Target URL": {
        "total_tested": 14,
        "dead_links": 7,
        "coverage_percentage": 50.0
      }
    },
    "summary": {
      "total_tested": 14,
      "total_dead": 7,
      "overall_coverage_percentage": 50.0
    }
  }
}

Shell 补全

deadfinder completion bash > /etc/bash_completion.d/deadfinder
deadfinder completion zsh  > ~/.zsh/completion/_deadfinder
deadfinder completion fish > ~/.config/fish/completions/deadfinder.fish

贡献

欢迎贡献！如果您有改进想法或想报告错误：

Fork 这个仓库。
创建一个新分支用于您的功能或错误修复（例如 feature/awesome-feature 或 bugfix/annoying-bug）。
进行修改。
提交修改并附上清晰的说明。
推送到分支。
向我们的 main 分支提交 Pull Request（PR）。

deadfinder

最受欢迎

安装