當您需要將已上傳至OSS的文件、圖片、視頻等資源下載到本地時，可以使用ossutil的cp命令。您也可以按照本文示例，下載多個文件、下載時限速，或者在已開啟版本控制的Bucket內下載指定版本文件。
注意事項
要下載文件，您必須具有
oss:GetObject或oss:ListObjects權限。具體操作，請參見為RAM用戶授權自定義的權限策略。從ossutil 1.6.16版本開始，命令行中Binary名稱支持直接使用ossutil，您無需根據系統刷新Binary名稱。如果您的ossutil版本低于1.6.16，則需要根據系統刷新Binary名稱。更多信息，請參見命令行工具ossutil命令參考。
當您在OSS ON云盒中使用該命令時：
將配置文件中的Endpoint替換為云盒Endpoint。更多信息，請參見云盒Endpoint。
在本文已有示例的基礎上添加--sign-version、--region以及--cloudbox-id選項。關于這三個選項的具體用法，請參見通用選項。
命令格式
ossutil cp cloud_url file_url
[-r, --recursive]
[-f --force]
[-u --update]
[--maxdownspeed <value>]
[--disable-ignore-error]
[--only-current-dir]
[--bigfile-threshold <value>]
[--part-size <value>]
[--checkpoint-dir <value>]
[--range <value>]
[--encoding-type <value>]
[--include <value>]
[--exclude <value>]
[--meta <value>]
[--acl <value>]
[--snapshot-path <value>]
[--disable-crc64]
[--payer <value>]
[--partition-download <value>]
[-j, --job <value>]
[--parallel <value>]
[--version-id <value>]
[--start-time <value>]
[--end-time <value>]參數及選項說明如下：
配置項 | 說明 |
cloud_url | OSS文件路徑。格式為 |
file_url | 本地文件路徑。例如Linux系統文件路徑 |
-r, --recursive | 遞歸操作。當指定該選項時，ossutil會對Bucket下所有符合條件的Object進行操作，否則只對指定的單個Object進行操作。 |
-f --force | 強制操作，不進行詢問提示。 |
-u，--update | 只有當目標文件不存在，或源文件的最后修改時間晚于目標文件時，ossutil才會執行下載操作。 |
--maxdownspeed | 最大下載速度，單位為KB/s。默認值為0，表示不限制下載速度。 |
--disable-ignore-error | 批量操作時不忽略錯誤。 |
--only-current-dir | 僅下載當前目錄下的文件，忽略子目錄及子目錄下的文件。 |
--bigfile-threshold | 設置斷點續傳文件的大小閾值，單位為字節。 默認值：100 MB 取值范圍：0~9223372036854775807 |
--part-size | 設置分片大小，單位為字節。默認情況下ossutil會根據文件大小自行計算合適的分片大小值。 取值范圍：1~9223372036854775807 |
--checkpoint-dir | 指定斷點續傳記錄信息所在的目錄。斷點續傳操作失敗時，ossutil會自動創建名為 |
--range | 下載目標文件的指定字段，并保存為一個新的文件，字段從0開始編號。
|
--encoding-type | 文件名稱的編碼方式。取值為url。如果不指定該選項，則表示文件名稱未經過編碼。 |
--include | 包含符合指定條件的所有文件。 更多信息，請參見include和exclude選項。 |
--exclude | 不包含符合指定條件的文件。 更多信息，請參見include和exclude選項。 |
--meta | 設置文件的元數據，格式為 |
--acl | 文件的讀寫權限ACL。取值如下：
|
--snapshot-path | 指定保存下載文件時的快照信息所在的目錄。在下一次下載文件時，ossutil會讀取指定目錄下的快照信息進行增量下載。 |
--disable-crc64 | 關閉CRC64數據校驗。默認情況下，ossutil進行數據傳輸時都會打開CRC64校驗。 |
--payer | 請求的支付方式。如果希望訪問指定路徑下的資源產生的流量、請求次數等費用由請求者支付，請將此選項的值設置為requester。 |
--partition-download | 用于分區下載。該選項取值格式為 |
-j，--job | 多文件操作時的并發任務數，默認值為3，取值范圍為1~10000。 |
--parallel | 單文件操作時的并發任務數，取值范圍為1~10000。 如果不設置此選項，默認由ossutil根據操作類型和文件大小自行決定。 |
--version-id | 下載指定版本的文件，僅支持在已開啟版本控制的Bucket內使用。 |
--start-time | Unix時間戳。如果輸入這個選項，最后更新時間早于該時間的Object會被忽略。 說明 僅1.7.18及以上版本支持設置該參數。關于如何升級版本，請參見update（ossutil版本升級）。 |
--end-time | Unix時間戳。如果使用該選項，則最后更新時間晚于通過此選項指定時間的Object會被忽略。 說明
|
從以上命令格式中的-j，--jobs和--parallel選項得知，當ossutil自行設置的默認并發數達不到用戶的性能要求時，您可以自行調整這兩個選項來升降性能。默認情況下，ossutil會根據文件大小來計算parallel個數。當批量下載大文件時，實際的并發數為jobs個數乘以parallel個數。
當ECS虛擬機或者服務器在網絡、內存、CPU等資源不是特別大的情況下，建議將并發數調整到100以下。如果網絡、內存、CPU等資源沒有占滿，可以適當增加并發數。
由于線程間資源切換及搶奪等原因，如果并發數過大，ossutil下載性能可能會下降。此外，并發數過大還可能產生EOF錯誤。所以請根據實際的機器情況調整-j，--jobs和--parallel選項的數值。如果要進行壓測，可在一開始時調低這兩項數值，然后逐漸調大直至找到最優值。
示例環境
本文以Linux系統為例，將OSS內的文件下載到本地。您在實際使用中，請根據您的系統和使用環境修改對應參數。示例環境如下：
操作系統：Linux
目標Bucket：examplebucket
目標Bucket指定目錄：destfolder
本地文件：examplefile.txt（根目錄下的文件）
本地文件夾：localfolder（根目錄下的文件夾）
下載單個文件
下載文件時如果未指定文件名，則默認使用原文件名保存在本地。如果指定文件名，則按照指定文件名保存在本地。
沿用原文件名保存文件
ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/按指定文件名保存文件
ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/example.txt
下載多個文件
ossutil不支持通過直接指定多個文件名的方式下載多個文件。您可以通過以下方式下載多個文件：
下載某一類文件
如果您希望同時下載多個文件名規律的文件，例如這些文件均包含相同前綴或者后綴，此時您可以結合--include和--exclude選項在下載時選擇符合條件的文件。
下載所有文件格式不為JPG的文件
ossutil cp oss://examplebucket/destfolder/ localfolder/ --exclude "*.jpg" -r下載所有文件名包含abc且不是JPG和TXT格式的文件
ossutil cp oss://examplebucket/destfolder/ localfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r
下載文件夾（包含子目錄）
下載某一個文件夾（包含子目錄）下所有文件的示例如下：
ossutil cp -r oss://examplebucket/destfolder/ localfolder/當批量下載失敗或者需要增量下載文件時，可以通過指定--update（可縮寫為-u）選項選擇跳過已經成功下載的文件。如果本地與OSS沒有同名文件，或本地同名文件的最后修改時間早于OSS文件，ossutil會下載該文件。如果本地已有同名文件，且文件的最后修改時間晚于OSS內文件時，ossutil會跳過該文件。示例如下：
ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --update下載文件夾（不包含子目錄）
如果您僅希望下載當前目錄而忽略子目錄下的文件時，可以通過指定--only-current-dir選項。示例如下：
ossutil cp oss://examplebucket/destfolder/ localfolder/ --only-current-dir -r下載文件夾（指定時間戳）
當某一個文件夾（包含子目錄）下的文件修改時間在北京時間2023年10月31日10:09:18至2023年10月31日12:55:58內時，才會被下載。示例如下：
ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --start-time 1698718158 --end-time 1698728158下載Bucket根目錄下的所有文件
將examplebucket根目錄下的所有文件下載到本地localfolder/目錄，示例如下：
ossutil cp -r oss://examplebucket localfolder/
下載時限速
您可以在下載文件時，結合--maxdownspeed選項來限制下載的最大速度，單位為KB/s。示例如下：
下載文件并設置限速為1 MB/s
ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/ --maxdownspeed 1024下載文件夾并設置限速為1 MB/s
ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --maxdownspeed 1024
范圍下載
下載文件時，可以通過--range選項指定下載范圍。例如將examplefile.txt的第10到第20個字符作為一個文件下載到本地，命令如下：
ossutil cp oss://examplebucket/destfolder/examplefile.txt localfolder/ --range=10-20
Succeed: Total num: 1, size: 11. OK num: 1(download 1 objects).下載并生成快照信息
批量下載時，如果指定--snapshot-path選項，ossutil在指定的目錄下生成文件下載的快照信息，在下一次指定該選項下載時，ossutil會讀取指定路徑下的快照信息進行增量下載。詳情請參見上傳并生成快照。
ossutil cp -r oss://examplebucket/destfolder/ localfolder/ --snapshot-path=path 在已開啟版本控制的Bucket內下載指定版本文件
開啟Bucket的版本控制后，針對數據的覆蓋和刪除操作將會以歷史版本的形式保存下來。您可以在cp命令中增加--version-id選項下載指定版本文件，命令如下：
ossutil cp oss://my-bucket/test.jpg localfolder/ --version-id CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk使用--version-id選項前，需使用ls --all-versions命令獲取文件的versionid。
--version-id選項僅支持在已開啟版本控制的Bucket內使用。開啟Bucket版本控制命令請參見bucket-versioning（版本控制）。
通用選項
當您需要通過命令行工具ossutil切換至另一個地域的Bucket時，可以通過-e選項指定該Bucket所屬的Endpoint。當您需要通過命令行工具ossutil切換至另一個阿里云賬號下的Bucket時，可以通過-i選項指定該賬號的AccessKey ID，并通過-k選項指定該賬號的AccessKey Secret。
您需要根據Bucket所在地域填寫對應的Endpoint。更多信息，請參見訪問域名和數據中心。
例如，您需要將另一個阿里云賬號下，華東2（上海）地域下存儲空間examplebucket根目錄下的文件exampleobject.txt下載至本地目錄localfolder下，命令如下：
ossutil cp oss://examplebucket/exampleobject.txt localfolder/ -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H****關于此命令的其他通用選項的更多信息，請參見通用選項。