نحوه دانلود فایل با curl

Q: تفاوت curl -o و curl -O چیست؟

-o filename دانلود را با نام فایل دقیقی که مشخص میکنید ذخیره میکند. -O نام فایل را از URL استخراج کرده و از آن استفاده میکند. از -o وقتی نام یا مسیر سفارشی میخواهید استفاده کنید؛ از -O وقتی نام فایل سمت سرور مناسب است.

Q: چرا curl فایل خالی یا HTML دانلود میکند به جای فایل واقعی؟

احتمالاً URL یک ریدایرکت HTTP (301 یا 302) برمیگرداند. به طور پیشفرض، curl خود پاسخ ریدایرکت را ذخیره میکند — نه محتوای نهایی. -L را اضافه کنید تا ریدایرکتها به طور خودکار دنبال شوند: curl -L -o file URL.

Q: چگونه فایل نیمهدانلودشده را با curl ادامه دهم؟

از curl -C - -o filename URL استفاده کنید. فلگ -C - اندازه فایل موجود را تشخیص داده و هدر Range ارسال میکند تا فقط بایتهای باقیمانده را درخواست کند. سرور باید از درخواستهای range پشتیبانی کند.

Q: چگونه سرعت دانلود را در curl محدود کنم؟

از --limit-rate با مقدار و پسوند استفاده کنید: curl --limit-rate 500k -o file URL سرعت را به 500 KB/s محدود میکند. پسوندها: k (KB/s)، M (MB/s)، G (GB/s).

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: چگونه با curl از سرور FTP فایل دانلود کنم؟

از curl -u user:pass -o localfile ftp://host/path/file استفاده کنید. curl به طور بومی از FTP، FTPS (FTP over 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 را در فایل ذخیره کنید و چه دانلودهای دسته‌ای را در اسکریپت شل خودکار کنید، 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 ذخیره می‌کند. برای مثال، اگر URL با /data.csv تمام شود، curl فایلی به نام data.csv در دایرکتوری فعلی ایجاد می‌کند.
کاربرد رایج: از -O استفاده کنید وقتی نام فایل سمت سرور معنادار است و نیازی به تغییر نام ندارید. می‌توانید چندین فلگ -O برای دانلود چند فایل در یک دستور استفاده کنید. توجه: اگر URL شامل نام فایل نباشد (مثلاً با / تمام شود)، curl با خطا مواجه می‌شود — به جای آن از -o استفاده کنید.

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

curl -L: دنبال کردن ریدایرکت‌ها

عملکرد: فلگ -L (یا --location) باعث می‌شود curl به طور خودکار ریدایرکت‌های HTTP را دنبال کند — 301 (Moved Permanently)، 302 (Found)، 307 و 308. بدون -L، curl خود پاسخ ریدایرکت را برمی‌گرداند نه محتوای واقعی.
کاربرد رایج: اکثر URL‌های دانلود حداقل یک بار ریدایرکت دارند (مثلاً از HTTP به HTTPS، یا از یک URL کوتاه به فایل واقعی). همیشه -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 پشتیبانی کند.
کاربرد رایج: اگر دانلود بزرگی به دلیل مشکل شبکه یا timeout قطع شد، کافی است همان دستور را با افزودن -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 ترکیب کنید. وقتی URL یک endpoint 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 دانلود می‌کند به جای فایل واقعی؟

احتمالاً URL یک ریدایرکت HTTP (301 یا 302) برمی‌گرداند. به طور پیش‌فرض، curl خود پاسخ ریدایرکت را ذخیره می‌کند — نه محتوای نهایی. -L را اضافه کنید تا ریدایرکت‌ها به طور خودکار دنبال شوند: curl -L -o file URL.

چگونه فایل نیمه‌دانلودشده را با curl ادامه دهم؟

از curl -C - -o filename URL استفاده کنید. فلگ -C - اندازه فایل موجود را تشخیص داده و هدر Range ارسال می‌کند تا فقط بایت‌های باقیمانده را درخواست کند. سرور باید از درخواست‌های range پشتیبانی کند.

چگونه سرعت دانلود را در curl محدود کنم؟

از --limit-rate با مقدار و پسوند استفاده کنید: curl --limit-rate 500k -o file URL سرعت را به 500 KB/s محدود می‌کند. پسوندها: k (KB/s)، M (MB/s)، G (GB/s).

آیا 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.

چگونه با curl از سرور FTP فایل دانلود کنم؟

از curl -u user:pass -o localfile ftp://host/path/file استفاده کنید. curl به طور بومی از FTP، FTPS (FTP over 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 برای mirror بازگشتی وب‌سایت ساده‌تر است و منطق تلاش مجدد داخلی دارد. 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.