مرجع Wrangler الكامل | دليل Cloudflare Workers

ما هو Wrangler؟

أداة سطر الأوامر الرسمية من Cloudflare لإدارة مشاريع Workers

⚡

إدارة Workers

أنشئ، طور، وانشر مشاريع Cloudflare Workers بسهولة من خلال سطر الأوامر بدون الحاجة للوحة التحكم.

🗄️

إدارة KV Store

أنشئ قواعد بيانات KV، أضف بيانات، احذفها، وادمجها مع مشروعك مباشرة من Wrangler.

🔐

إدارة الأسرار

أضف مفاتيح API وكلمات المرور والمتغيرات الحساسة بأمان دون تخزينها في الكود.

📊

مراقبة Logs

تابع سجلات الأخطاء والطلبات في الوقت الفعلي أثناء التطوير والإنتاج.

🌍

نشر فوري

انشر مشروعك على شبكة Cloudflare العالمية بضغطة زر واحدة خلال ثوانٍ.

🛠️

بيئة تطوير محلية

شغّل Worker على جهازك قبل النشر مع محاكاة كاملة لبيئة Cloudflare.

💡

متى نستخدم Wrangler؟

Wrangler هو الأداة الأساسية عند العمل مع Cloudflare Workers. إذا كان مشروعك يحتاج باكند (API, Functions, Logic) فـ Wrangler هو الخيار الأمثل. أما إذا كانت صفحة ثابتة فقط، فـ GitHub + Vercel كافيان.

التثبيت والإعداد

خطوات تثبيت Wrangler وربطه بحساب Cloudflare

1

تثبيت Wrangler عبر npm

Wrangler يحتاج Node.js 16.13.0 أو أحدث. تأكد من تثبيت Node.js أولاً.

🖥️ Terminal

# تثبيت Wrangler بشكل عام (موصى به)
npm install -g wrangler

# أو تثبيت محلي في المشروع
npm install wrangler --save-dev

2

تسجيل الدخول لحساب Cloudflare

بعد التثبيت، سجّل الدخول لربط Wrangler بحسابك. سيُفتح متصفح لإكمال العملية.

🖥️ Terminal

# تسجيل الدخول (يفتح المتصفح تلقائياً)
wrangler login

# التحقق من تسجيل الدخول
wrangler whoami

3

التحقق من التثبيت

تأكد أن Wrangler يعمل بشكل صحيح واعرف رقم الإصدار.

🖥️ Terminal

# التحقق من الإصدار
wrangler --version

# عرض المساعدة العامة
wrangler --help

⚠️

ملاحظة مهمة

Wrangler يحفظ بيانات المصادقة في مجلد ~/.wrangler/. لا تشارك هذا المجلد مع أحد. إذا واجهت مشاكل في تسجيل الدخول، جرّب wrangler logout ثم wrangler login مرة أخرى.

إنشاء مشروع جديد

أنشئ أول Worker خاص بك بخطوات بسيطة

📁 إنشاء مشروع جديد

# إنشاء مشروع Worker جديد
wrangler init my-worker

# الدخول للمجلد
cd my-worker

# تثبيت الاعتماديات
npm install

# تشغيل محلي
wrangler dev

سيُنشئ هذا الأمر هيكل المشروع الأساسي مع ملف src/index.js و package.json.

📁 إنشاء مشروع Pages مع Functions

# إنشاء مشروع Pages مع Functions
wrangler pages project create my-pages-project

# نشر مجلد static على Pages
wrangler pages deploy ./dist --project-name=my-pages-project

📁 إضافة Wrangler لمشروع موجود

# داخل مجلد المشروع الموجود
wrangler init --yes

# هذا يُنشئ wrangler.jsonc بدلاً من wrangler.toml
# (نستخدم JSON الآن كما تُفضل Cloudflare)

📂 هيكل المشروع بعد الإنشاء

بعد تشغيل wrangler init، ستحصل على هذا الهيكل:

my-worker/
├── src/
│   └── index.js          // ملف الـ Worker الرئيسي
├── wrangler.jsonc        // إعدادات المشروع (JSON بدلاً من TOML)
├── package.json          // اعتماديات المشروع
├── .gitignore
└── README.md

التشغيل المحلي (Local Development)

شغّل Worker على جهازك قبل النشر مع محاكاة كاملة

🖥️ Terminal

# تشغيل محلي على البورت 8787 (افتراضي)
wrangler dev

# تشغيل على بورت معين
wrangler dev --port 3000

# تشغيل على IP محدد (للاختبار من أجهزة أخرى)
wrangler dev --ip 0.0.0.0

# تشغيل بدون فتح المتصفح تلقائياً
wrangler dev --no-open

# تشغيل بـ Inspector للـ Debugging
wrangler dev --inspect

✅

مميزات التشغيل المحلي

يُحاكي wrangler dev بيئة Cloudflare بالكامل: Fetch API، KV، Durable Objects، Cache API، وحتى الـ Bindings. لا حاجة للنشر للاختبار!

الأوامر الأساسية

جميع أوامر Wrangler مع الشرح والأمثلة - اضغط "نسخ" لأي أمر

الأمر	الوصف	مثال
wrangler login	تسجيل الدخول لحساب Cloudflare	wrangler login
wrangler logout	تسجيل الخروج وحذف بيانات المصادقة	wrangler logout
wrangler whoami	عرض الحساب المسجل حالياً	wrangler whoami
wrangler init	إنشاء مشروع Worker جديد	wrangler init my-worker
wrangler dev	تشغيل محلي للتطوير	wrangler dev --port 8787
wrangler deploy	نشر Worker على Cloudflare	wrangler deploy
wrangler tail	مشاهدة Logs في الوقت الفعلي	wrangler tail
wrangler delete	حذف Worker من Cloudflare	wrangler delete
wrangler publish	نشر Worker (الأمر القديم، استخدم deploy)	wrangler deploy (موصى به)

إدارة KV Store

إنشاء قواعد بيانات KV وإدارتها من سطر الأوامر

🗄️ إنشاء Namespace جديد

# إنشاء KV Namespace جديد
wrangler kv namespace create "MY_KV"

# الناتج: سيعطيك ID للـ Namespace
# احفظ هذا ID، ستحتاجه في wrangler.jsonc

🗄️ إضافة بيانات

# إضافة قيمة نصية
wrangler kv key put --binding=MY_KV "user:123" '{"name":"أحمد","age":25}'

# إضافة من ملف
wrangler kv key put --binding=MY_KV "config" --path=./config.json

# إضافة مع Expiration (بالثواني)
wrangler kv key put --binding=MY_KV "temp" "value" --expiration=3600

🗄️ قراءة وحذف

# قراءة قيمة
wrangler kv key get --binding=MY_KV "user:123"

# حذف مفتاح
wrangler kv key delete --binding=MY_KV "user:123"

# حذف كل المفاتيح (⚠️ حذر!)
wrangler kv namespace delete --namespace-id=<ID>

🗄️ عرض المفاتيح

# عرض كل المفاتيح
wrangler kv key list --binding=MY_KV

# عرض كل الـ Namespaces
wrangler kv namespace list

🔗 ربط KV في wrangler.jsonc

بعد إنشاء الـ Namespace، أضفه في الإعدادات:

📄 wrangler.jsonc

{
  "name": "my-worker",
  "main": "src/index.js",
  "compatibility_date": "2024-01-01",
  "kv_namespaces": [
    {
      "binding": "MY_KV",
      "id": "your-namespace-id-here"
    }
  ]
}

💡

تلميح: إنشاء KV من Dashboard

يمكنك أيضاً إنشاء KV Namespace من Cloudflare Dashboard → Workers & Pages → KV. ثم انسخ الـ ID والصقه في wrangler.jsonc. هذه الطريقة أسهل للمبتدئين.

إدارة الأسرار والمتغيرات

أضف API Keys وكلمات المرور بأمان دون تخزينها في الكود

1

إضافة Secret

الأسرار تُخزن مشفرة في Cloudflare ولا تظهر في الكود أو Logs.

🔐 Terminal

# إضافة Secret (سيطلب إدخال القيمة)
wrangler secret put API_KEY

# إضافة Secret لبيئة محددة
wrangler secret put API_KEY --env production

2

استخدام Secret في الكود

بعد الإضافة، يمكنك الوصول للـ Secret مباشرة من خلال env.

📄 src/index.js

export default {
  async fetch(request, env, ctx) {
    // الوصول للـ Secret مباشرة
    const apiKey = env.API_KEY;

    // استخدامه في طلب API
    const response = await fetch('https://api.example.com/data', {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });

    return response;
  }
};

3

حذف Secret

إذا احتجت لحذف Secret قديم أو تغييره.

🔐 Terminal

# حذف Secret
wrangler secret delete API_KEY

# عرض قائمة Secrets
wrangler secret list

⚠️

فرق بين Secrets و Variables

Secrets: مشفرة، تُستخدم للمفاتيح الحساسة (API Keys, Passwords).
Variables: غير مشفرة، تُستخدم للإعدادات العامة (URLs, Feature Flags).
أضف Variables من Cloudflare Dashboard → Workers → Settings → Variables.

النشر على Cloudflare

أوامر النشر للإنتاج والبيئات المختلفة

🚀 Terminal

# نشر على البيئة الافتراضية (production)
wrangler deploy

# نشر على بيئة محددة
wrangler deploy --env staging

# نشر مع اسم Worker مختلف
wrangler deploy --name my-worker-v2

# نشر مع تجاوز التحقق
wrangler deploy --no-verify

🌍 إعدادات البيئات (Environments)

يمكنك إعداد بيئات متعددة في wrangler.jsonc:

📄 wrangler.jsonc

{
  "name": "my-worker",
  "main": "src/index.js",
  "compatibility_date": "2024-01-01",
  "vars": {
    "ENVIRONMENT": "production"
  },
  "env": {
    "staging": {
      "vars": {
        "ENVIRONMENT": "staging"
      }
    }
  }
}

مراقبة Logs (Tail)

تابع الطلبات والأخطاء في الوقت الفعلي

📊 Terminal

# مراقبة Logs في الوقت الفعلي
wrangler tail

# مراقبة Logs لبيئة محددة
wrangler tail --env production

# تصدير Logs لملف
wrangler tail --format json > logs.json

# مراقبة مع فلترة (مثال: أخطاء فقط)
wrangler tail --format pretty

💡

Console.log في الـ Worker

أي console.log() في كود الـ Worker سيظهر مباشرة في wrangler tail. استخدمه للـ Debugging بسهولة.

ربط دومين مخصص

ربط Worker بدومين خاص بك

1

إضافة Route من Wrangler

ربط Worker بمسار معين في دومينك.

🌐 Terminal

# إضافة Route
wrangler route publish "api.yourdomain.com/*"

# عرض Routes الموجودة
wrangler route list

# حذف Route
wrangler route delete "api.yourdomain.com/*"

2

إضافة Route في wrangler.jsonc

يمكنك أيضاً تعريف Routes مباشرة في الإعدادات.

📄 wrangler.jsonc

{
  "name": "my-worker",
  "main": "src/index.js",
  "routes": [
    {
      "pattern": "api.yourdomain.com/*",
      "custom_domain": true
    }
  ]
}

⚠️

متطلبات الدومين المخصص

يجب أن يكون الدومين مضافاً في حساب Cloudflare الخاص بك. اذهب إلى Cloudflare Dashboard → Websites → Add Site. بعدها يمكنك ربط الـ Worker به.

حل المشاكل الشائعة

أكثر المشاكل التي تواجه المستخدمين مع Wrangler

❌

خطأ: Not Authenticated

الحل: شغّل wrangler login مرة أخرى. إذا استمرت المشكلة، احذف مجلد ~/.wrangler/ وأعد المحاولة.

❌

خطأ: KV Namespace Not Found

الحل: تأكد من أن الـ ID صحيح في wrangler.jsonc. استخدم wrangler kv namespace list للتأكد.

❌

خطأ: Port Already in Use

الحل: استخدم بورت آخر: wrangler dev --port 3001 أو أغلق التطبيق الذي يستخدم البورت 8787.

❌

خطأ: Module Not Found

الحل: شغّل npm install لتثبيت الاعتماديات. تأكد أن node_modules موجود.

❌

خطأ: Deploy Failed

الحل: تأكد من أن compatibility_date محدد في wrangler.jsonc. جرّب تحديثه لتاريخ اليوم.

❌

خطأ: Secret Not Found

الحل: تأكد من إضافة الـ Secret للبيئة الصحيحة. استخدم wrangler secret list للتأكد.

ملخص سريع (Cheat Sheet)

جميع الأوامر في مكان واحد للنسخ السريع

📋 Cheat Sheet - انسخ ما تحتاجه

# ======= التثبيت والمصادقة =======
npm install -g wrangler          # تثبيت Wrangler
wrangler login                   # تسجيل الدخول
wrangler logout                  # تسجيل الخروج
wrangler whoami                 # عرض الحساب

# ======= إنشاء المشروع =======
wrangler init my-worker           # إنشاء مشروع
wrangler init --yes               # إضافة لمشروع موجود

# ======= التطوير المحلي =======
wrangler dev                     # تشغيل محلي
wrangler dev --port 3000          # بورت محدد
wrangler dev --no-open            # بدون فتح المتصفح

# ======= النشر =======
wrangler deploy                  # نشر للإنتاج
wrangler deploy --env staging    # نشر لبيئة staging
wrangler delete                  # حذف Worker

# ======= KV Store =======
wrangler kv namespace create "MY_KV"     # إنشاء KV
wrangler kv namespace list              # عرض الكل
wrangler kv key put --binding=MY_KV "key" "value"  # إضافة
wrangler kv key get --binding=MY_KV "key"          # قراءة
wrangler kv key delete --binding=MY_KV "key"       # حذف
wrangler kv key list --binding=MY_KV              # عرض المفاتيح

# ======= Secrets =======
wrangler secret put API_KEY      # إضافة Secret
wrangler secret list             # عرض Secrets
wrangler secret delete API_KEY  # حذف Secret

# ======= Logs =======
wrangler tail                     # مراقبة Logs
wrangler tail --format pretty      # تنسيق جميل

# ======= Routes =======
wrangler route list              # عرض Routes
wrangler route publish "domain.com/*"  # إضافة Route
wrangler route delete "domain.com/*"   # حذف Route