當您需要將本地文件、圖片、視頻等資源上傳到OSS，或者需要上傳大文件至OSS時，可以使用ossutil的cp命令。您也可以指定--include和--exclude選項，批量上傳符合指定條件的文件。
注意事項
要上傳文件，您必須具有
oss:PutObject權限。具體操作，請參見為RAM用戶授權自定義的權限策略。從ossutil 1.6.16版本開始，命令行中Binary名稱支持直接使用ossutil，您無需根據系統刷新Binary名稱。如果您的ossutil版本低于1.6.16，則需要根據系統刷新Binary名稱。更多信息，請參見命令行工具ossutil命令參考。
使用cp命令上傳文件時，ossutil會根據文件大小自動選擇不同的上傳方式：
當您在OSS ON云盒中使用該命令時：
將配置文件中的Endpoint替換為云盒Endpoint。更多信息，請參見云盒Endpoint。
在本文已有示例的基礎上添加--sign-version、--region以及--cloudbox-id選項。關于這三個選項的具體用法，請參見通用選項。
命令格式
ossutil cp file_url cloud_url
[-r, --recursive]
[-f --force]
[-u --update]
[--maxupspeed <value>]
[--enable-symlink-dir]
[--disable-all-symlink]
[--disable-ignore-error]
[--only-current-dir]
[--bigfile-threshold <value>]
[--part-size <value>]
[--checkpoint-dir <value>]
[--encoding-type <value>]
[--include <value>]
[--exclude <value>]
[--meta <value>]
[--acl <value>]
[--snapshot-path <value>]
[--disable-crc64]
[--disable-dir-object]
[--payer <value>]
[--tagging <value>]
[-j, --job <value>]
[--parallel <value>]
[--start-time <value>]
[--end-time <value>]參數及選項說明如下：
配置項 | 說明 |
file_url | 本地文件路徑。例如Linux系統文件路徑 |
cloud_url | OSS文件路徑。格式為 |
-r, --recursive | 遞歸操作。當指定該選項時，ossutil會對Bucket下所有符合條件的Object進行操作，否則只對指定的單個Object進行操作。 |
-f --force | 強制操作，不進行詢問提示。 |
-u，--update | 只有當目標文件不存在，或源文件的最后修改時間晚于目標文件時，ossutil才會執行上傳操作。 |
--maxupspeed | 最大上傳速度，單位為KB/s。默認值為0，表示不限制上傳速度。 |
--enable-symlink-dir | 上傳鏈接子目錄，默認不上傳。 |
--disable-all-symlink | 上傳時忽略所有的軟鏈接子文件以及軟鏈接子目錄。 |
--disable-ignore-error | 批量操作時不忽略錯誤。 |
--only-current-dir | 僅上傳當前目錄下的文件，忽略子目錄及子目錄下的文件。 |
--bigfile-threshold | 設置斷點續傳文件的大小閾值，單位為字節。 默認值：100 MB 取值范圍：0~9223372036854775807 |
--part-size | 設置分片大小，單位為字節。默認情況下ossutil會根據文件大小自行計算合適的分片大小值。 取值范圍：1~9223372036854775807 |
--checkpoint-dir | 指定斷點續傳記錄信息所在的目錄。斷點續傳操作失敗時，ossutil會自動創建名為 |
--encoding-type | 文件名稱的編碼方式。取值為url。如果不指定該選項，則表示文件名稱未經過編碼。 |
--include | 包含符合指定條件的所有文件。語法規范和使用示例，請參見批量上傳符合條件的文件。 |
--exclude | 不包含任何符合指定條件的文件。語法規范和使用示例，請參見批量上傳符合條件的文件。 |
--meta | 文件的元數據。包括部分HTTP標準屬性（HTTP Header）以及以 |
--acl | 文件的讀寫權限ACL。取值如下：
|
--snapshot-path | 指定保存上傳文件時的快照信息所在的目錄。在下一次上傳文件時，ossutil會讀取指定目錄下的快照信息進行增量上傳。 |
--disable-crc64 | 關閉CRC64數據校驗。默認情況下，ossutil進行數據傳輸時都會打開CRC64校驗。 |
--disable-dir-object | 表示上傳文件時不為目錄生成Object。 |
--payer | 請求的支付方式。如果希望訪問指定路徑下的資源產生的流量、請求次數等費用由請求者支付，請將此選項的值設置為requester。 |
--tagging | 上傳文件時設置標簽信息，格式為 |
-j，--jobs | 多文件操作時的并發任務數，默認值為3，取值范圍為1~10000。 |
--parallel | 單文件操作時的并發任務數，取值范圍為1~10000。 如果不設置此選項，默認由ossutil根據操作類型和文件大小自行決定。 |
--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中。您在實際使用中，請根據您的系統和使用環境修改對應參數。本文涉及的通用示例說明如下：
本地文件：examplefile.txt（根目錄下的文件）
本地文件夾：localfolder（根目錄下的文件夾）
目標Bucket：examplebucket
目標Bucket指定目錄：desfolder
簡單上傳
當您需要將本地文件、圖片、視頻等資源上傳到OSS，可以使用ossutil，示例如下：
上傳單個文件
上傳文件時，如果不指定上傳至OSS的文件名，則默認使用原文件名進行保存；如果指定文件名，則按照指定的文件名保存在OSS中。
ossutil cp examplefile.txt oss://examplebucket/desfolder/僅上傳文件夾內的文件
使用cp命令時增加-r選項，可以只將本地文件夾內的文件上傳到OSS指定路徑。
ossutil cp -r localfolder/ oss://examplebucket/desfolder/上傳文件夾內的文件并指定時間戳
將本地文件夾內的文件上傳到OSS指定路徑，文件修改時間限定在北京時間2023年10月31日10:09:18至2023年10月31日12:55:58內。
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --start-time 1698718158 --end-time 1698728158上傳文件夾及文件夾內的文件
使用cp命令時增加-r選項，并在OSS指定路徑下添加本地文件夾名稱，可以將本地文件夾以及文件夾內的文件上傳到OSS指定路徑。 對于文件夾內的文件夾，OSS會對應創建0 KB大小、以正斜線（/）結尾的Object；對于指定的文件夾，OSS不會創建對應的Object。如果您需要創建對應的Object，您可以使用mkdir（創建目錄）。
ossutil cp -r localfolder/ oss://examplebucket/desfolder/localfolder/上傳單個文件并指定--meta選項
上傳文件的同時可以使用--meta選項設置文件的meta信息，其內容格式為
header:value#header:value...。ossutil cp examplefile.txt oss://examplebucket/desfolder/examplefile.txt --meta=Cache-Control:no-cache#Content-Encoding:gzip上傳文件夾并跳過已有文件
批量上傳失敗重傳時，可以指定--update（可縮寫為-u）選項跳過已經上傳成功的文件，實現增量上傳。示例如下：
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u上傳文件到開通了請求者付費模式的Bucket
ossutil cp localfolder/examplefile.txt oss://examplebucket/ --payer=requester僅上傳當前目錄下的文件，忽略子目錄
ossutil cp localfolder/ oss://examplebucket/desfolder/ --only-current-dir -r上傳時不為目錄生成Object
OSS的目錄是用一個0 KB大小，名稱以正斜線（/）結尾的Object模擬的。上傳時增加--disable-dir-object參數，ossutil不會為該目錄生成Object，但您仍可以在OSS控制臺看到對應的目錄結構。當您刪除目錄內的文件時，該目錄也會消失。
ossutil cp localfolder/ oss://examplebucket/desfolder/ --disable-dir-object -r上傳軟鏈接子目錄下的文件
ossutil cp localfolder/ oss://examplebucket/desfolder/ --enable-symlink-dir -r上傳時忽略所有的軟鏈接子文件以及軟鏈接子目錄
ossutil cp localfolder/ oss://examplebucket/desfolder/ -r --disable-all-symlink
上傳時限速
您可以在上傳文件時，結合--maxupspeed選項來限制上傳的最大速度，單位為KB/s。示例如下：
上傳文件并設置限速為1 MB/s
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --maxupspeed 1024上傳文件夾并設置限速為1 MB/s
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --maxupspeed 1024
上傳并設置對象標簽
您可以在上傳文件時，通過--tagging選項設置文件對象標簽，多個標簽以and（&）符號隔開。示例如下：
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --tagging "abc=1&bcd=2&……"關于對象標簽的更多說明請參見object-tagging（對象標簽）。
上傳并指定存儲類型
您可以在上傳文件時，通過--meta選項設置文件存儲類型。存儲類型可選值為：
Standard：標準存儲
IA：低頻訪問
Archive：歸檔存儲
ColdArchive：冷歸檔存儲
DeepColdArchive：深度冷歸檔存儲
在OSS ON云盒使用場景中，僅支持Standard類型。
如果上傳時未指定存儲類型，則以存儲空間的存儲類型為準。更多信息，請參見存儲類型概述。
上傳并指定存儲類型的示例如下：
上傳單個文件并指定存儲類型為低頻訪問類型
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:IA上傳文件夾并指定存儲類型為標準存儲類型
ossutil cp localfolder/ oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:Standard -r
上傳并指定讀寫權限ACL
您可以在上傳文件時，通過--acl選項設置文件的ACL。文件ACL可選值為：
default：繼承Bucket（默認）
private：私有
public-read：公共讀
public-read-write：公共讀寫
示例如下：
上傳單個文件并指定ACL為私有
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --acl private上傳文件夾并指定ACL為公共讀
ossutil cp localfolder/ oss://examplebucket/desfolder/ --acl public-read -r
上傳并指定加密方式
您可以在上傳文件時指定文件的服務器端加密方式，將文件加密后保存在Bucket內。 示例如下：
在OSS ON云盒使用場景中，僅支持AES256。
上傳文件并指定加密方式為OSS完全托管，加密算法為AES256
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:AES256上傳文件并指定加密方式為OSS完全托管，加密算法為SM4
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:SM4上傳文件并指定加密方式為KMS，指定加密算法為AES256，不指定CMK ID
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS使用KMS加密時，會產生少量KMS密鑰使用費用，詳情請參見KMS計費標準。
上傳文件并指定加密方式為KMS，指定加密算法為SM4，指定CMK ID
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-data-encryption:SM4#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******
有關服務器端加密功能介紹，請參見服務器端加密。
上傳并生成快照
批量上傳時，如果指定--snapshot-path選項，ossutil在指定的目錄下生成文件上傳的快照，記錄成功上傳的文件的本地lastModifiedTime，在下次上傳時通過比較lastModifiedTime來決定是否跳過相同文件，所以在使用該選項時，請確保兩次上傳期間沒有其他用戶更改了OSS上對應的Object。--snapshot-path選項適用于加速增量上傳的場景。示例如下：
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --snapshot-path=path ossutil不會主動刪除snapshot-path文件夾中的快照信息。為避免快照信息過多，請定期刪除snapshot-path文件夾內無用的快照。
由于讀寫snapshot信息需要額外開銷，當待批量上傳的文件數量較少、網絡狀況較好、或有其他用戶操作相同Object時，不建議使用該選項。針對以上情況，您可以使用--update選項來增量上傳。
--update選項和--snapshot-path選項可以同時使用，ossutil會優先根據snapshot-path信息判斷是否跳過此文件，如果不滿足跳過條件，再根據--update判斷是否跳過此文件。
批量上傳符合條件的文件
批量上傳時，如果指定--include和--exclude選項，ossutil會批量上傳符合指定條件的文件。
--include和--exclude選項支持格式：
通配符星號（*）：匹配所有字符。例如：*.txt表示匹配所有TXT格式的文件。
通配符問號（？）：匹配單個字符。例如：abc?.jpg表示匹配所有文件名為abc+任意單個字符的JPG格式的文件，如abc1.jpg。
[sequence]：匹配序列的任意字符，例如：abc[1-5].jpg表示匹配文件名為abc1.jpg~abc5.jpg的文件。
[!sequence]：匹配序列外的任意字符，例如：abc[!0-7].jpg表示匹配文件名不為abc0.jpg~abc7.jpg的文件。
一條規則中可以包含多個include（包含）和exclude（排除）條件，且每個文件從左到右逐一運用每個規則，直至最后才能最終確定匹配的結果。例如指定生效的文件夾中包含名為test.txt的文件，匹配不同的規則產生的結果如下。
規則一：
--include "*test*" --exclude "*.txt"，當規則匹配到--include "*test*"，匹配的結果為test.txt符合條件；當規則繼續匹配到--exclude "*.txt"時，因test.txt文件名包含.txt，所以被排除。則匹配的最終結果為test.txt不符合條件。規則二：
--exclude "*.txt" --include "*test*"，當規則匹配到--exclude "*.txt"，匹配的結果為test.txt不符合條件；當規則繼續匹配到--include "*test*"，因test.txt文件名包含test，所以符合條件。則匹配的最終結果為test.txt符合條件。規則三：
--include "*test*" --exclude "*.txt" --include "te?t.txt"，當規則匹配到--include "*test*"，匹配的結果為test.txt符合條件；當規則繼續匹配到--exclude "*.txt"時，因test.txt文件名包含.txt，所以被排除；當規則最后匹配到--include "te?t.txt"時，因test.txt符合條件，所以被包含。則匹配的最終結果為test.txt符合條件。
設定條件時不支持目錄格式，例如--include "/usr/test/.jpg"。
示例如下：
上傳所有文件格式為TXT的文件
ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*.txt" -r上傳所有文件名包含abc且不是JPG和TXT格式的文件
ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r
通用選項
當您需要通過命令行工具ossutil切換至另一個地域的Bucket時，可以通過-e選項指定該Bucket所屬的Endpoint。當您需要通過命令行工具ossutil切換至另一個阿里云賬號下的Bucket時，可以通過-i選項指定該賬號的AccessKey ID，并通過-k選項指定該賬號的AccessKey Secret。
例如，您需要將本地文件exampleobject.txt上傳至另一個阿里云賬號下，華東2（上海）地域的存儲空間examplebucket的destfolder目錄下，命令如下：
ossutil cp exampleobject.txt oss://examplebucket/desfolder/ -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H****關于此命令的其他通用選項的更多信息，請參見通用選項。