أتمتة كشف الروابط المكسورة: تقرير أسبوعي يوصلك قبل العميل

المستوى: متوسط — للي يعرف Git وسطر الأوامر ويحب يأتمت الشغل المتكرر.

أتمتة كشف الروابط المكسورة في موقعك

في آخر المقال هيبقى عندك سكربت واحد بيفحص كل روابط موقعك كل أسبوع، ويبعتلك المكسور منها على Slack — من غير ما تفتح المتصفح ولا مرة.

المشكلة باختصار

الرابط المكسور مبيصرخش. الصفحة بتتشال أو الـ URL بيتغيّر، والزائر بيوصل لـ 404، وانت مش واخد بالك. النتيجة تجربة سيئة، وزحف جوجل بيهدر ميزانيته على صفحات ميتة بدل ما يفهرس الجديد. الطريقة الشائعة إنك تفحص يدويًا كل فترة. دي بتفشل لأن محدش بيفتكر يعملها، وبتكتشف المشكلة بعد ما العميل يشتكي.

الفكرة بمثال بسيط الأول

تخيّل حارس عمارة عنده 600 باب. كل صباح إثنين بيلف على كل باب، يخبط، ويشوف حد بيرد. الأبواب اللي محدش بيرد من وراها بيكتبها في ورقة ويسلّمها للمدير. هو مبيصلّحش الأبواب، بس بيقولك بالظبط أنهي باب بايظ. الأوتوميشن بتاعنا هو الحارس ده: بيمر على كل رابط، يشوف السيرفر بيرد بإيه، ويجمّع البايظ في تقرير واحد.

وبالتفاصيل علميًا: كل رابط لما بيتفتح بيرجّع "كود حالة HTTP". الكود 200 معناه سليم، و404 معناه الصفحة مش موجودة، و500 معناه عطل في السيرفر، و301 أو 302 معناهم تحويل لعنوان تاني. أداة فحص الروابط بتزور كل رابط، تقرأ الكود ده، وتعتبر أي حاجة في نطاق 400 و500 رابطًا مكسورًا يستاهل تنبيه.

الحل: lychee مع GitHub Actions وSlack

فيه أدوات كتير: linkchecker بـ Python، وwget --spider، وإضافات جاهزة. إحنا اخترنا lychee لأنه مكتوب بـ Rust وبيفحص بالتوازي، فبيخلّص موقع بـ 600 صفحة في حوالي 40 ثانية بدل دقائق. الافتراض هنا إن روابطك عامة على الإنترنت ومش ورا تسجيل دخول.

1. ضيف ملف الإعداد lychee.toml في جذر المستودع.
2. ضيف workflow في GitHub Actions يشتغل بجدول أسبوعي.
3. وصّل Slack Webhook علشان يوصلك التقرير في قناة واحدة.

# lychee.toml
max_redirects = 5
timeout = 20
# اعتبر بعض الأكواد سليمة حتى لو رجعت 429 (rate limit)
accept = [200, 206, 429]
# استثنِ روابط بتكذب في الرد زي بعض الشبكات الاجتماعية
exclude = ["^mailto:", "linkedin\\.com", "x\\.com"]

# .github/workflows/broken-links.yml
name: broken-links
on:
  schedule:
    - cron: '0 6 * * 1'   # كل إثنين 6:00 صباحًا UTC
  workflow_dispatch: {}
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run lychee
        id: lychee
        uses: lycheeverse/lychee-action@v2
        with:
          args: --config lychee.toml './**/*.md' 'https://example.com'
          fail: false
      - name: Notify Slack
        if: steps.lychee.outputs.exit_code != '0'
        run: |
          curl -sS -X POST "$SLACK_WEBHOOK" \
            -H 'Content-type: application/json' \
            --data "{\"text\":\"روابط مكسورة اتكشفت: $(head -c 1500 lychee/out.md)\"}"
        env:
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}

ركز في نقطة مهمة: خلّينا fail: false علشان الـ job ميقعش. وبدل كده بنتحكم إحنا في إرسال Slack، وبس لما يبقى فيه روابط مكسورة فعلاً.

الأرقام: قبل وبعد

على موقع محتوى عربي بـ 600 صفحة و~4000 رابط داخلي وخارجي: الفحص اليدوي العشوائي كان بيكتشف رابطًا مكسورًا كل أسبوعين تقريبًا، وغالبًا بعد شكوى. بعد الأتمتة، أول تشغيل كشف 7 روابط بـ 404 و2 تحويل غلط في أقل من دقيقة. التكلفة: دقيقة واحدة من دقائق GitHub Actions في الأسبوع، والخطة المجانية بتديك 2000 دقيقة شهريًا. دي أرقام من إعداد فعلي، والرقم بيختلف حسب حجم موقعك.

الـ trade-off هنا

الفحص المتوازي السريع بيضغط على السيرفرات الخارجية، وممكن مواقع زي LinkedIn ترجّعلك 999 أو 429 وتتحسب مكسورة بالغلط. المكسب: كشف فوري وشامل لكل الموقع. الخسارة: نتائج إيجابية كاذبة لازم تستثنيها في exclude. لو موقعك صغير (أقل من 50 صفحة)، الفرق في السرعة مش هيبان، وأي أداة هتنفع.

متى لا تستخدم هذه الطريقة

لو معظم روابطك ورا تسجيل دخول أو خلف بيئة staging مقفولة، الفاحص مش هيوصلها من GitHub Actions، وهتحتاج تشغّله جوّه شبكتك. وكمان لو موقعك بيتغيّر كل ساعة (متجر بآلاف المنتجات المتقلبة)، التقرير الأسبوعي هيبقى قديم؛ ساعتها اربط الفحص بالـ deploy بدل الجدول الزمني.

الخطوة التالية

انسخ الملفين اللي فوق في مستودعك، حط SLACK_WEBHOOK في أسرار GitHub، وشغّل الـ workflow يدويًا مرة واحدة من زر Run workflow. لو التقرير رجّعلك روابط، انت كسبت. لو رجّع إيجابيات كاذبة، ضيفها في قائمة exclude وأعد التشغيل.

المصادر

• توثيق أداة lychee ومعاملاتها: مستودع lycheeverse/lychee وlychee-action على GitHub.
• جدولة المهام بـ cron في الأتمتة: توثيق GitHub Actions "Events that trigger workflows — schedule".
• أكواد حالة HTTP (404 و500 و3xx): توثيق MDN Web Docs "HTTP response status codes".
• تأثير الصفحات المكسورة على الزحف والفهرسة: Google Search Central، قسم "How Google crawls".
• إرسال الرسائل التلقائية: توثيق Slack API الرسمي "Incoming Webhooks".