اعمل Short Links داخلي بـ Cloudflare Workers وKV

هتكسب أداة روابط قصيرة تحت سيطرتك، تعدل وجهة الحملة من مكان واحد، وتقلل شغل التعديل اليدوي من 12 دقيقة تقريبًا إلى دقيقتين.

مستوى القارئ: متوسط

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

لو عندك حملة إعلانية أو newsletter وفيها رابط طويل، المشكلة مش في طول الرابط بس. المشكلة إن الرابط بيتنسخ في البريد، السوشيال، QR، وصف الفيديو، ورسائل العملاء. أول ما الصفحة تتغير، بتبدأ رحلة تعديل مرهقة.

الطريقة الشائعة إنك تخزن الروابط في Spreadsheet وتطلب من الفريق ينسخ آخر نسخة. الطريقة دي بتفشل لما شخص يستخدم نسخة قديمة، أو لما تحتاج تغيّر الوجهة بسرعة أثناء حملة شغالة. البديل العملي: short link داخلي مثل go.example.com/ramadan-offer يقرأ الوجهة من KV ثم يعمل redirect.

الفكرة بمثال قبل الشرح

ركز في السيناريو ده. عندك متجر صغير بيستقبل 50K زيارة في اليوم. فريق التسويق نشر الرابط /spring في 6 قنوات. بعد ساعتين، صفحة الهبوط الجديدة بقت أسرع وفيها tracking أحسن. بدل ما تعدل كل قناة، تغيّر قيمة واحدة في KV:

npx wrangler kv key put spring "https://example.com/new-landing?utm_campaign=spring" --binding LINKS

من اللحظة دي، أي زائر يفتح go.example.com/spring يروح للوجهة الجديدة. المفهوم العلمي هنا بسيط: الـ Worker يستقبل الطلب، يستخرج الـ slug من المسار، يسأل Workers KV عن القيمة، ثم يرجع 302 Redirect. Cloudflare KV مناسب لهذا لأنه key-value store موزع عالميًا ومربوط بالـ Worker من خلال binding رسمي.

الخطوات التنفيذية

1. ابدأ مشروع Worker جديد: npm create cloudflare@latest short-links.
2. ادخل للمجلد وثبت Wrangler لو مش موجود: npm i -D wrangler.
3. اعمل KV namespace باسم واضح: npx wrangler kv namespace create LINKS.
4. انسخ الـ id الناتج داخل wrangler.jsonc أو wrangler.toml تحت kv_namespaces.
5. اكتب كود Worker يقرأ الـ slug ويرجع redirect.
6. اختبر محليًا بـ npx wrangler dev.
7. انشر بـ npx wrangler deploy، وبعدها اربطه بدومين مثل go.example.com.

{
  "name": "short-links",
  "main": "src/index.js",
  "compatibility_date": "2026-04-25",
  "kv_namespaces": [
    {
      "binding": "LINKS",
      "id": "ضع-id-الخاص-بك-هنا"
    }
  ],
  "routes": [
    {
      "pattern": "go.example.com",
      "custom_domain": true
    }
  ]
}

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const slug = url.pathname.replace(/^\//, "").trim();

    if (!slug) {
      return new Response("Missing short link slug", { status: 400 });
    }

    const destination = await env.LINKS.get(slug);

    if (!destination) {
      return new Response("Short link not found", { status: 404 });
    }

    if (!destination.startsWith("https://")) {
      return new Response("Invalid destination", { status: 500 });
    }

    return Response.redirect(destination, 302);
  }
};

استخدم 302 بدل 301 لو الروابط قابلة للتغيير. 301 ممكن يتخزن عند المتصفح أو محركات البحث بشكل أشرس، وده ضد فكرة إن الرابط الداخلي يتغير بسرعة.

التحقق من أنه يعمل

ضيف رابط تجريبي، ثم افتحه بـ curl. النتيجة المتوقعة إنك تشوف header باسم location فيه الوجهة الطويلة.

npx wrangler kv key put demo "https://example.com/pricing?utm_source=short" --binding LINKS

curl -I https://go.example.com/demo
# HTTP/2 302
# location: https://example.com/pricing?utm_source=short

لو ظهر 404، غالبًا الـ slug غير موجود في KV. لو ظهر 500، راجع إن القيمة تبدأ بـ https://. الافتراض هنا إن كل وجهاتك public URLs وليست روابط داخلية حساسة.

الأرقام والـ trade-offs

في فريق صغير، تعديل رابط حملة يدويًا في 4 أماكن ممكن ياخد 10 إلى 15 دقيقة، غير احتمال نسيان قناة. باستخدام KV، التعديل يتحول إلى أمر واحد ياخد حوالي دقيقتين مع اختبار سريع. المكسب واضح: نقطة تحكم واحدة. التكلفة: أنت بقيت مسؤول عن naming convention، صلاحيات Wrangler، ومراجعة الروابط قبل نشرها.

الـ trade-off هنا إن Workers KV ممتاز للقراءات الكثيرة والكتابات القليلة، لكنه مش قاعدة بيانات relational ولا مناسب لتحديث نفس المفتاح عشرات المرات في الثانية. حسب حدود Cloudflare الحالية، الكتابة لنفس المفتاح محدودة بـ 1 write/second، وقيمة المفتاح نفسها لها حدود معلنة. لذلك استخدمه لروابط حملات وlanding pages، مش لنظام analytics لحظي.

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

لا تستخدمها لو محتاج لوحة إدارة كاملة، صلاحيات متعددة، تقارير clicks تفصيلية، أو A/B testing متقدم. في الحالة دي استخدم أداة متخصصة أو ابنِ backend كامل مع قاعدة بيانات. كمان لا تستخدمها لو الفريق غير مستعد لإدارة secrets وCloudflare permissions؛ الخطأ هنا ممكن يوجّه حملة كاملة لوجهة غلط.

المصادر

• Cloudflare KV namespaces
• Wrangler KV commands
• Cloudflare Workers custom domains
• Cloudflare Workers KV limits

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

اختار حملة واحدة عندك، واعمل لها slug واحد فقط اليوم. لو التعديل من KV أخد أكثر من دقيقتين، المشكلة غالبًا في naming أو صلاحيات النشر، مش في Cloudflare Workers نفسه.