查找死链（失效链接）

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

在寻找 v1（Ruby gem）？ 它现在位于 legacy/v1 分支，并继续发布 deadfinder gem 以提供缺陷修复和安全版本。main 分支承载 Crystal 重写版本（v2+）。

安装

Homebrew

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

Chocolatey（Windows）

从 2.1.0 之后的版本开始：

choco install deadfinder

Docker

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

预编译二进制文件

从最新发布版下载适用于你平台的压缩包，解压后将 deadfinder（Windows 上为 deadfinder.exe）放到你的 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 解析器的 postinstall —— 缺少它时 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
# or: just build

使用 In

CLI

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

GitHub Action

固定到特定的发布标签。@latest 不是有效的 Actions 引用。

steps:
- name: Run DeadFinder
  uses: hahwul/deadfinder@v2       # tracks the latest 2.x — pin a specific tag (e.g. @2.1.0) for stricter reproducibility
  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"
    # insecure: false
    # match:  ""
    # ignore: ""
    # limit: 0
    # output_format: json
    # coverage: true
    # visualize: report.png
    # fail_on_dead: true       # fail the step when a dead link is found
    # method: auto             # auto / head / get
    # retry: 2
    # delay: 0                 # ms between requests to the same host
    # accept_status: "403,999"
    # dead_status: ""
    # target_concurrency: 10
    # check_anchors: false

- name: Output Handling
  run: echo '${{ steps.broken-link.outputs.output }}'

如果你发现了死链并希望自动将其添加为 issue，请参阅“自动化死链检测”一文。

用法

Usage: deadfinder <command> [options]

Commands:
  pipe                        Scan the URLs from STDIN
  file <FILE>                 Scan the URLs from File (`-` for STDIN)
  url <URL>                   Scan the Single URL
  sitemap <SITEMAP-URL>       Scan the URLs from sitemap
  completion <SHELL>          Generate completion script (bash/zsh/fish)
  version                     Show version

Options:
  -r, --include30x                 Include 30x redirections as dead links
  -c, --concurrency=N              Number of concurrent workers (default: 50)
      --target-concurrency=N       Targets scanned in parallel; total in-flight
                                   requests stay capped at -c (default: 10)
  -t, --timeout=N                  Timeout in seconds (default: 10)
      --method=METHOD              Link check method: auto, head, get (default: auto)
      --retry=N                    Retry transient failures N times (default: 2)
      --delay=MS                   Minimum ms between requests to the same host
      --accept-status=LIST         Statuses to treat as alive (e.g. 200,403,999)
      --dead-status=LIST           Statuses to treat as dead (e.g. 500-599)
      --exclude-status=LIST        Alias of --dead-status
  -o, --output=FILE                File to write results (`-` for stdout)
  -f, --output_format=FORMAT       Output format: json, yaml, toml, csv, sarif (default: json)
  -H, --headers=HEADER             Custom HTTP headers for initial request
      --worker_headers=HEADER      Custom HTTP headers for worker requests
      --user_agent=UA              User-Agent string
  -p, --proxy=PROXY                Proxy server (HTTP and HTTPS CONNECT)
      --proxy_auth=USER:PASS       Proxy authentication
  -k, --insecure                   Skip TLS certificate verification (not recommended)
  -m, --match=PATTERN              Match URL pattern (regex)
  -i, --ignore=PATTERN             Ignore URL pattern (regex)
  -s, --silent                     Silent mode
  -v, --verbose                    Verbose mode
      --debug                      Debug mode
      --limit=N                    Limit number of URLs to scan
      --check-anchors              Verify #fragment targets exist in the linked document
      --coverage                   Enable coverage tracking and reporting
  -F, --fail-on-dead               Exit with code 2 when anything dead is found
      --visualize=PATH             Generate visualization PNG
  -h, --help                       Show help

模式

# Scan the URLs from STDIN (multiple URLs)
cat urls.txt | deadfinder pipe

# Scan the URLs from a file
deadfinder file urls.txt

# `-` and other non-regular files (process substitution, /dev/stdin, FIFOs) work too
deadfinder file -  < urls.txt
deadfinder file <(subfinder -d example.com -silent | httpx -silent)

# Scan a single URL
deadfinder url https://www.hahwul.com

# Scan the URLs from a sitemap
deadfinder sitemap https://www.hahwul.com/sitemap.xml

URL 列表格式（`pipe` / `file`）

每行一个 URL。列表在扫描前会被规范化：

去除首尾空白，并丢弃开头的 UTF-8 BOM
跳过空行和 # 注释
重复的 URL 只扫描一次
不是绝对 http:// / https:// URL 的行会被报告并跳过
--limit N 只统计真实目标，达到上限后停止读取输入

# production
https://www.hahwul.com
https://www.hahwul.com/cullinan/

# staging
https://staging.hahwul.com

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
    }
  }
}

CI 用法

默认情况下，扫描始终以 0 退出，因此失效链接绝不会导致构建失败。使用 -F / --fail-on-dead 选择启用该行为，当发现任何失效项时以 2 退出（1 仍保留用于用法和 I/O 错误）：

deadfinder sitemap https://example.com/sitemap.xml --fail-on-dead
echo $?   # 2 when a dead link or a dead target was found

-o - 将报告流式输出到 stdout —— 在该模式下日志会转到 stderr，因此结构化输出可以安全地通过管道传递：

deadfinder

最受欢迎

安装