كيفية تحميل الملفات باستخدام curl

Q: ما الفرق بين curl -o و curl -O؟

-o filename يحفظ الملف المحمّل باسم الملف الذي تحدده أنت. -O يستخرج اسم الملف من عنوان URL ويستخدمه. استخدم -o عندما تريد اسماً أو مساراً مخصصاً؛ استخدم -O عندما يكون اسم الملف البعيد مناسباً كما هو.

Q: كيف أستأنف تحميل ملف تم تحميله جزئياً باستخدام curl؟

استخدم curl -C - -o filename URL. الخيار -C - يكتشف حجم الملف الموجود ويرسل ترويسة Range لطلب البايتات المتبقية فقط. يجب أن يدعم الخادم طلبات النطاق لكي يعمل هذا.

Q: كيف أحدد سرعة التحميل في curl؟

استخدم --limit-rate مع قيمة ولاحقة: curl --limit-rate 500k -o file URL يحدد السرعة بـ 500 كيلوبايت/ثانية. اللواحق: k (كيلوبايت/ثانية)، M (ميغابايت/ثانية)، G (غيغابايت/ثانية).

Q: هل يمكن لـ curl تحميل ملفات متعددة دفعة واحدة؟

نعم. استخدم عدة خيارات -O: curl -O URL1 -O URL2 -O URL3. يحمّلها curl بالتتابع. للتحميل المتوازي، مرر قائمة عناوين URL إلى xargs -P 4 -I {} curl -O {}.

Q: كيف أحمّل ملفاً يتطلب مصادقة؟

لـ HTTP Basic Auth: curl -u user:pass -o file URL. لرموز Bearer: curl -H "Authorization: Bearer TOKEN" -o file URL. لمفاتيح API في الترويسات: curl -H "X-API-Key: KEY" -o file URL.

Q: كيف أحمّل ملفات من خادم FTP باستخدام curl؟

استخدم curl -u user:pass -o localfile ftp://host/path/file. يدعم curl بروتوكولات FTP و FTPS (FTP عبر TLS) و SFTP (SSH FTP) أصلياً. لـ FTP المجهول، احذف -u.

Q: كيف أحمّل ملفات كبيرة بشكل موثوق باستخدام curl؟

ادمج -C - (استئناف عند الفشل) و --retry 5 (إعادة محاولة تلقائية) و --retry-delay 10 و -L (تتبع إعادة التوجيه): curl -C - --retry 5 --retry-delay 10 -L -o file URL. يتعامل هذا مع مشاكل الشبكة تلقائياً.

Q: كيف أعرض شريط تقدم عند التحميل باستخدام curl؟

استخدم curl -# -o file URL لشريط تقدم بسيط. مخرجات curl الافتراضية تعرض بالفعل سرعة النقل والنسبة المئوية والوقت المقدر. للسكريبتات، استخدم -s لإخفاء كل المخرجات.

Q: هل يمكنني تحديد مجلد التحميل في curl؟

مع curl 7.73+، استخدم --output-dir /path/to/dir مع -O. للإصدارات الأقدم، حدد المسار الكامل بـ -o /path/to/dir/filename. أضف --create-dirs إذا لم يكن المجلد موجوداً بعد.

curl هي واحدة من أكثر أدوات سطر الأوامر تنوعاً لتحميل الملفات عبر HTTP و HTTPS و FTP وعشرات البروتوكولات الأخرى. سواء كنت بحاجة لحفظ استجابة API واحدة في ملف أو أتمتة تحميل دفعات في سكريبت shell، فإن curl لديها خيار لذلك. يغطي هذا الدليل كل خيارات التحميل — من الحفظ الأساسي باستخدام -o و -O إلى استئناف عمليات النقل المتقطعة بـ -C -، وتحديد عرض النطاق بـ --limit-rate، وعرض أشرطة التقدم. كل خيار يتضمن شرحاً واضحاً وأنماط استخدام شائعة ومثالاً جاهزاً للنسخ.

مرجع سريع لخيارات التحميل

الخيار	الوصف
-o	كتابة المخرجات في ملف مسمى بدلاً من stdout
-O	كتابة المخرجات في ملف بنفس اسم الملف البعيد
-L	تتبع إعادة توجيه HTTP 3xx تلقائياً
-C -	متابعة/استئناف نقل ملف سابق
--limit-rate	تحديد سرعة النقل بمعدل محدد
--max-filesize	رفض تحميل الملفات الأكبر من الحجم المحدد
-J	استخدام ترويسة Content-Disposition لتسمية الملف
-#	عرض تقدم النقل كشريط تقدم بسيط
-u	توفير اسم المستخدم:كلمة المرور لمصادقة الخادم
--retry	إعادة محاولة النقل عند حدوث أخطاء مؤقتة (عدد المرات)
--retry-delay	الانتظار بالثواني بين محاولات إعادة المحاولة
-T	رفع ملف محلي إلى عنوان URL (PUT بشكل افتراضي)
--create-dirs	إنشاء المجلدات المحلية حسب الحاجة عند حفظ المخرجات
-s	إخفاء مقياس التقدم ورسائل الخطأ
--output-dir	حفظ ملف(ات) المخرجات في المجلد المحدد (curl 7.73+)

-o

كتابة المخرجات في ملف مسمى بدلاً من stdout

-O

كتابة المخرجات في ملف بنفس اسم الملف البعيد

-L

تتبع إعادة توجيه HTTP 3xx تلقائياً

-C -

متابعة/استئناف نقل ملف سابق

--limit-rate

تحديد سرعة النقل بمعدل محدد

--max-filesize

رفض تحميل الملفات الأكبر من الحجم المحدد

-J

استخدام ترويسة Content-Disposition لتسمية الملف

عرض تقدم النقل كشريط تقدم بسيط

-u

توفير اسم المستخدم:كلمة المرور لمصادقة الخادم

--retry

إعادة محاولة النقل عند حدوث أخطاء مؤقتة (عدد المرات)

--retry-delay

الانتظار بالثواني بين محاولات إعادة المحاولة

-T

رفع ملف محلي إلى عنوان URL (PUT بشكل افتراضي)

--create-dirs

إنشاء المجلدات المحلية حسب الحاجة عند حفظ المخرجات

-s

إخفاء مقياس التقدم ورسائل الخطأ

--output-dir

حفظ ملف(ات) المخرجات في المجلد المحدد (curl 7.73+)

curl -o: الحفظ باسم ملف محدد

ما يفعله: الخيار -o (أو --output) يخبر curl بحفظ جسم الاستجابة في ملف تحدده أنت. بدونه، يطبع curl الاستجابة في stdout (الطرفية). يمكنك استخدام أي اسم ملف ومسار — سينشئ curl الملف أو يستبدل ملفاً موجوداً.
الاستخدام الشائع: استخدم -o عندما تحتاج للتحكم باسم الملف بالضبط أو الحفظ في مجلد محدد. يعمل مع أي بروتوكول — HTTP و HTTPS و FTP و SFTP والمزيد. ادمجه مع -L للتعامل مع إعادة التوجيه و -s للتشغيل الصامت في السكريبتات.

$ curl -o report.pdf https://example.com/files/report.pdf

curl -O: الحفظ باسم الملف البعيد

ما يفعله: الخيار -O (أو --remote-name) يحفظ الملف المحمّل باستخدام اسم الملف المستخرج من عنوان URL. مثلاً، إذا انتهى العنوان بـ /data.csv، ينشئ curl ملفاً باسم data.csv في المجلد الحالي.
الاستخدام الشائع: استخدم -O عندما يكون اسم الملف البعيد ذا معنى ولا تحتاج لتغييره. يمكنك تمرير عدة خيارات -O لتحميل ملفات متعددة في أمر واحد. ملاحظة: إذا لم يحتوِ العنوان على اسم ملف (مثلاً ينتهي بـ /)، سيفشل curl — استخدم -o بدلاً من ذلك.

$ curl -O https://example.com/files/data.csv

curl -L: تتبع إعادة التوجيه

ما يفعله: الخيار -L (أو --location) يجعل curl يتبع إعادة توجيه HTTP تلقائياً — 301 (تم النقل دائماً) و 302 (تم العثور) و 307 و 308. بدون -L، يعيد curl استجابة إعادة التوجيه نفسها بدلاً من المحتوى الفعلي.
الاستخدام الشائع: معظم روابط التحميل تعيد التوجيه مرة واحدة على الأقل (مثلاً من HTTP إلى HTTPS، أو من رابط قصير إلى الملف الفعلي). ادمج دائماً -L مع -o أو -O عند تحميل الملفات. بشكل افتراضي يتبع curl حتى 50 إعادة توجيه؛ غيّر ذلك بـ --max-redirs.

$ curl -L -o latest.tar.gz https://github.com/user/repo/releases/latest/download/app.tar.gz

curl -C -: استئناف التحميلات المتقطعة

ما يفعله: الخيار -C - (أو --continue-at -) يخبر curl بالكشف تلقائياً عن حجم الملف الجزئي الموجود واستئناف التحميل من حيث توقف. يجب أن يدعم الخادم ترويسة HTTP Range لكي يعمل هذا.
الاستخدام الشائع: إذا انقطع تحميل كبير بسبب مشكلة في الشبكة أو انتهاء المهلة، أعد تشغيل نفس الأمر مع إضافة -C -. سيرسل curl ترويسة Range: bytes=OFFSET- ويحمّل فقط البيانات المتبقية. هذا ضروري للملفات الكبيرة عبر اتصالات غير مستقرة.

$ curl -C - -o largefile.zip https://cdn.example.com/largefile.zip

curl --limit-rate: تحديد سرعة التحميل

ما يفعله: الخيار --limit-rate يضع حداً أقصى لسرعة التحميل (والرفع) بالمعدل المحدد. يقبل لواحق: k أو K لكيلوبايت/ثانية، m أو M لميغابايت/ثانية، g أو G لغيغابايت/ثانية.
الاستخدام الشائع: استخدم --limit-rate لتجنب إشباع عرض النطاق عند تحميل ملفات كبيرة، خاصة على الاتصالات المشتركة. مفيد أيضاً لاختبار كيفية تعامل تطبيقك مع الاستجابات البطيئة.

$ curl --limit-rate 1M -o bigfile.iso https://mirror.example.com/bigfile.iso

curl --max-filesize: الإلغاء إذا كان الملف كبيراً جداً

ما يفعله: الخيار --max-filesize يخبر curl بإلغاء النقل إذا تجاوز حجم الملف المتوقع (من ترويسة Content-Length) الحد المحدد. يمكن استخدام لواحق مثل k و M و G.
الاستخدام الشائع: استخدمه في السكريبتات لمنع التحميلات الكبيرة غير المتوقعة من استهلاك مساحة القرص. لاحظ أن ليس كل الخوادم ترسل Content-Length — في هذه الحالة لا يمكن لـ curl فرض هذا الحد ويستمر التحميل بشكل طبيعي.

$ curl --max-filesize 100M -o update.bin https://example.com/update.bin

curl -J: استخدام اسم الملف المقترح من الخادم

ما يفعله: الخيار -J (أو --remote-header-name) يخبر curl باستخدام اسم الملف المحدد في ترويسة Content-Disposition من الخادم بدلاً من استخراجه من عنوان URL. هذا شائع في واجهات API للتحميل التي تعيد ملفات بأسماء ذات معنى.
الاستخدام الشائع: ادمج دائماً -J مع -O. هذا مفيد عندما يكون العنوان نقطة نهاية API (مثل /export?format=csv) لكن الخادم يعيد اسم ملف صحيح في الترويسات. ملاحظة أمنية: الخادم يتحكم في اسم الملف، لذا استخدمه مع خوادم موثوقة فقط.

$ curl -L -O -J https://example.com/api/export?format=csv

curl -#: عرض شريط التقدم

ما يفعله: الخيار -# (أو --progress-bar) يستبدل مقياس التقدم المفصل الافتراضي بشريط تقدم بسيط ###. هذا أسهل في القراءة للاستخدام التفاعلي.
الاستخدام الشائع: استخدم -# عند التحميل بشكل تفاعلي وتريد مؤشر تقدم نظيف. للسكريبتات، فضّل -s (صامت) أو مقياس التقدم الافتراضي. مخرجات curl الافتراضية تعرض بالفعل السرعة والنسبة المئوية والوقت المتبقي والحجم الكلي.

$ curl -# -o archive.tar.gz https://example.com/archive.tar.gz

خيارات تحميل إضافية

الخيار	الوصف
-u	توفير اسم المستخدم:كلمة المرور لمصادقة الخادم
--retry	إعادة محاولة النقل عند حدوث أخطاء مؤقتة (عدد المرات)
--retry-delay	الانتظار بالثواني بين محاولات إعادة المحاولة
-T	رفع ملف محلي إلى عنوان URL (PUT بشكل افتراضي)
--create-dirs	إنشاء المجلدات المحلية حسب الحاجة عند حفظ المخرجات
-s	إخفاء مقياس التقدم ورسائل الخطأ
--output-dir	حفظ ملف(ات) المخرجات في المجلد المحدد (curl 7.73+)

-u

توفير اسم المستخدم:كلمة المرور لمصادقة الخادم

--retry

إعادة محاولة النقل عند حدوث أخطاء مؤقتة (عدد المرات)

--retry-delay

الانتظار بالثواني بين محاولات إعادة المحاولة

-T

رفع ملف محلي إلى عنوان URL (PUT بشكل افتراضي)

--create-dirs

إنشاء المجلدات المحلية حسب الحاجة عند حفظ المخرجات

-s

إخفاء مقياس التقدم ورسائل الخطأ

--output-dir

حفظ ملف(ات) المخرجات في المجلد المحدد (curl 7.73+)

سيناريوهات تحميل واقعية

هذه الأمثلة تدمج عدة خيارات للتعامل مع مهام التحميل الشائعة التي ستواجهها في التطوير اليومي والسكريبتات.

تحميل ملفات متعددة دفعة واحدة

استخدم عدة خيارات -O لتحميل عدة ملفات في أمر واحد. يعالجها curl بالتتابع. للتحميل المتوازي، استخدم xargs أو GNU parallel.

$ curl -O https://example.com/file1.txt -O https://example.com/file2.txt -O https://example.com/file3.txt

التحميل من خادم FTP

يدعم curl بروتوكولات FTP و FTPS و SFTP أصلياً. أضف -u user:password للوصول المصادق. استخدم -O للحفاظ على اسم الملف البعيد.

$ curl -u user:pass -o backup.sql ftp://ftp.example.com/db/backup.sql

التحميل مع المصادقة

استخدم -u user:pass لـ Basic Auth، أو -H لتمرير رمز Bearer أو مفتاح API. ادمجه مع -L و -o لتحميل كامل.

$ curl -H "Authorization: Bearer eyJhbGciOi..." -L -o data.json https://api.example.com/export

تحميل موثوق مع الاستئناف وإعادة المحاولة

ادمج -C - (استئناف) و --retry (إعادة محاولة تلقائية عند الفشل) و -L (تتبع إعادة التوجيه) لتحميلات قوية تصمد أمام انقطاعات الشبكة.

$ curl -C - --retry 5 --retry-delay 10 -L -o largefile.zip https://cdn.example.com/largefile.zip

الأسئلة الشائعة حول التحميل باستخدام curl

ما الفرق بين curl -o و curl -O؟

-o filename يحفظ الملف المحمّل باسم الملف الذي تحدده أنت. -O يستخرج اسم الملف من عنوان URL ويستخدمه. استخدم -o عندما تريد اسماً أو مساراً مخصصاً؛ استخدم -O عندما يكون اسم الملف البعيد مناسباً كما هو.

لماذا يحمّل curl ملفاً فارغاً أو ملف HTML بدلاً من الملف الفعلي؟

من المحتمل أن العنوان يعيد توجيه HTTP (301 أو 302). بشكل افتراضي، يحفظ curl استجابة إعادة التوجيه نفسها — وليس المحتوى النهائي. أضف -L لتتبع إعادة التوجيه تلقائياً: curl -L -o file URL.

كيف أستأنف تحميل ملف تم تحميله جزئياً باستخدام curl؟

استخدم curl -C - -o filename URL. الخيار -C - يكتشف حجم الملف الموجود ويرسل ترويسة Range لطلب البايتات المتبقية فقط. يجب أن يدعم الخادم طلبات النطاق لكي يعمل هذا.

كيف أحدد سرعة التحميل في curl؟

استخدم --limit-rate مع قيمة ولاحقة: curl --limit-rate 500k -o file URL يحدد السرعة بـ 500 كيلوبايت/ثانية. اللواحق: k (كيلوبايت/ثانية)، M (ميغابايت/ثانية)، G (غيغابايت/ثانية).

هل يمكن لـ curl تحميل ملفات متعددة دفعة واحدة؟

نعم. استخدم عدة خيارات -O: curl -O URL1 -O URL2 -O URL3. يحمّلها curl بالتتابع. للتحميل المتوازي، مرر قائمة عناوين URL إلى xargs -P 4 -I {} curl -O {}.

كيف أحمّل ملفاً يتطلب مصادقة؟

لـ HTTP Basic Auth: curl -u user:pass -o file URL. لرموز Bearer: curl -H "Authorization: Bearer TOKEN" -o file URL. لمفاتيح API في الترويسات: curl -H "X-API-Key: KEY" -o file URL.

كيف أحمّل ملفات من خادم FTP باستخدام curl؟

استخدم curl -u user:pass -o localfile ftp://host/path/file. يدعم curl بروتوكولات FTP و FTPS (FTP عبر TLS) و SFTP (SSH FTP) أصلياً. لـ FTP المجهول، احذف -u.

كيف أحمّل ملفات كبيرة بشكل موثوق باستخدام curl؟

ادمج -C - (استئناف عند الفشل) و --retry 5 (إعادة محاولة تلقائية) و --retry-delay 10 و -L (تتبع إعادة التوجيه): curl -C - --retry 5 --retry-delay 10 -L -o file URL. يتعامل هذا مع مشاكل الشبكة تلقائياً.

كيف أعرض شريط تقدم عند التحميل باستخدام curl؟

استخدم curl -# -o file URL لشريط تقدم بسيط. مخرجات curl الافتراضية تعرض بالفعل سرعة النقل والنسبة المئوية والوقت المقدر. للسكريبتات، استخدم -s لإخفاء كل المخرجات.

هل يمكنني تحديد مجلد التحميل في curl؟

مع curl 7.73+، استخدم --output-dir /path/to/dir مع -O. للإصدارات الأقدم، حدد المسار الكامل بـ -o /path/to/dir/filename. أضف --create-dirs إذا لم يكن المجلد موجوداً بعد.

هل أستخدم curl أم wget لتحميل الملفات؟

كلاهما ممتاز. wget أبسط لنسخ المواقع العودي ولديه منطق إعادة محاولة مدمج. curl يدعم أكثر من 25 بروتوكولاً (ليس فقط HTTP/FTP)، وهو أفضل لاستدعاءات API والسكريبتات، ويدعم طرق مصادقة أكثر، ومتوفر على كل أنظمة التشغيل تقريباً.

كيف أستخدم curl في سكريبت bash لتحميل الملفات؟

استخدم curl -fsSL -o file URL: -f يفشل بصمت عند أخطاء HTTP (لا يُحفظ صفحة الخطأ)، -s صامت، -S يعرض الأخطاء حتى في الوضع الصامت، -L يتبع إعادة التوجيه. تحقق من رمز الخروج: if ! curl -fsSL -o file URL; then echo "Download failed"; exit 1; fi.