如何使用 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 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 token：curl -H "Authorization: Bearer TOKEN" -o file URL。標頭中的 API key：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: 如何可靠地下載大檔案？

組合 -C -（失敗時恢復）、--retry 5（自動重試）、--retry-delay 10 和 -L（跟隨重新導向）：curl -C - --retry 5 --retry-delay 10 -L -o file URL。這會自動處理網路中斷。

Q: 下載時如何顯示進度條？

使用 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+）

將輸出寫入指定檔案而非 stdout

將輸出寫入與遠端檔案同名的檔案

自動跟隨 HTTP 3xx 重新導向

繼續/恢復之前的檔案傳輸

將傳輸速度限制在指定速率

拒絕下載超過指定大小的檔案

使用 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（永久移動）、302（臨時移動）、307 和 308。不使用 -L 時，curl 傳回重新導向回應本身而非實際內容。
常見用法: 大多數下載 URL 至少重新導向一次（例如從 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 組合使用。當 URL 是 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 token 或 API key。與 -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 標頭僅請求剩餘位元組。伺服器必須支援範圍請求才能生效。

如何限制 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 token：curl -H "Authorization: Bearer TOKEN" -o file URL。標頭中的 API key：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。

如何可靠地下載大檔案？

組合 -C -（失敗時恢復）、--retry 5（自動重試）、--retry-delay 10 和 -L（跟隨重新導向）：curl -C - --retry 5 --retry-delay 10 -L -o file URL。這會自動處理網路中斷。

下載時如何顯示進度條？

使用 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 呼叫和腳本編寫，支援更多驗證方式，且幾乎在所有作業系統上都可用。

如何在 bash 腳本中使用 curl 下載檔案？

使用 curl -fsSL -o file URL：-f 在 HTTP 錯誤時靜默失敗（不儲存錯誤頁面），-s 靜默，-S 即使在靜默模式下也顯示錯誤，-L 跟隨重新導向。檢查退出碼：if ! curl -fsSL -o file URL; then echo "Download failed"; exit 1; fi。