deadfinder

التوثيق • التثبيت • Github Action • المساهمة • سجل التغييرات

الرابط الميت (الرابط المعطوب) هو رابط داخل صفحة ويب لا يمكن الاتصال به. يمكن أن يكون لهذه الروابط تأثير سلبي على تحسين محركات البحث (SEO) والأمان. تجعل هذه الأداة من السهل تحديدها وتعديلها.

هل تبحث عن الإصدار v1 (Ruby gem)؟ أصبح الآن موجودًا على الفرع legacy/v1 ويواصل نشر gem ‏deadfinder لإصدارات إصلاح الأخطاء والأمان. يستضيف الفرع 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 (deadfinder.exe على Windows) في مسار PATH الخاص بك.

Nix

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

البناء من المصدر

يتطلب Crystal >= 1.19.1 وcmake (من أجل خطوة postinstall الخاصة بمحلل HTML lexbor — وبدونه يفشل 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

الاستخدام في

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، فيرجى الرجوع إلى مقالة "Automating Dead Link Detection".

الاستخدام

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 واحد في كل سطر. تُطبَّع القائمة قبل الفحص:

• تُزال المسافات البيضاء المحيطة، وتُحذف علامة BOM الخاصة بـ UTF-8 في البداية
• تُتخطى الأسطر الفارغة وتعليقات #
• تُفحص عناوين URL المكررة مرة واحدة فقط
• تُبلَّغ الأسطر التي ليست عناوين URL مطلقة بصيغة http:// / https:// ويُتخطى تجاوزها
• يحسب --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: