全部產品
Search

搜尋本產品

    Object Storage Service：cp（拷貝檔案）

    文件中心

    Object Storage Service：cp（拷貝檔案）

    更新時間：Nov 06, 2025

    使用cp命令，將同一地區下的儲存空間（Bucket）內的檔案複製到目標Bucket，或者將檔案複製到相同儲存空間（Bucket）的其他目錄。

    注意事項

    • 不支援通過cp命令跨帳號或者跨地區拷貝檔案。如果您需要跨帳號或者跨地區拷貝（遷移）檔案，請使用線上遷移服務。

    • 目前只支援拷貝檔案，不支援拷貝未完成的分區（Part）。

    • 從ossutil 1.6.16版本開始，命令列中Binary名稱支援直接使用ossutil，無需根據系統重新整理Binary名稱。如果ossutil版本低於1.6.16，則需要根據系統重新整理Binary名稱。更多資訊，請參見命令列工具ossutil命令參考。

      許可權說明

      預設情況下，只有阿里雲帳號擁有所有API的操作許可權。RAM使用者或RAM角色需要被阿里雲帳號或帳號管理員通過RAM Policy或Bucket Policy授予相應的許可權才能執行此命令。

      API Action

      說明

      oss:GetObject

      拷貝同一地區下相同或不同儲存空間（Bucket）之間的檔案（Object）。

      oss:PutObject

      oss:GetObjectVersion

      可選。拷貝Object的特定版本時，需要此許可權。

      oss:GetObjectTagging

      可選。拷貝Object涉及對象標籤時，需要此許可權。

      oss:PutObjectTagging

      oss:GetObjectVersionTagging

      可選。拷貝Object並涉及特定版本標籤時，需要此許可權。

      kms:GenerateDataKey

      可選。拷貝Object涉及KMS伺服器端加密時，需要此許可權。

      kms:Decrypt

      命令格式

      ossutil cp cloud_url cloud_url [options]

      參數及選項說明如下：

      參數

      說明

      cloud_url

      分別填寫OSS源檔案和目標檔案路徑。格式為oss://bucketname/objectname。例如，將目標儲存空間examplebucket下的源檔案srcobject.jpg拷貝到相同儲存空間下的目標檔案destobject.jpg，則源檔案路徑填寫為oss://examplebucket/srcobject.jpg，目標檔案路徑填寫為oss://examplebucket/destobject.jpg。

      -r, --recursive

      遞迴操作。當指定該選項時，ossutil會對Bucket下所有合格Object進行操作，否則只對指定的單個Object進行操作。

      -f --force

      強制操作，不進行詢問提示。

      -u，--update

      只有當目標檔案不存在，或源檔案的最後修改時間晚於目標檔案時，ossutil才會執行拷貝操作。

      --disable-ignore-error

      大量操作時不忽略錯誤。

      --only-current-dir

      僅拷貝目前的目錄下的檔案，忽略子目錄及子目錄下的檔案。

      -bigfile-threshold

      設定斷點續傳檔案的大小閾值，單位為位元組。

      預設值：100 MB

      取值範圍：0~9223372036854775807

      --part-size

      設定分區大小，單位為位元組。預設情況下ossutil會根據檔案大小自行計算合適的分區大小值。

      取值範圍：1~9223372036854775807

      --checkpoint-dir

      指定斷點續傳記錄資訊所在的目錄。斷點續傳操作失敗時，ossutil會自動建立名為.ossutil_checkpoint的目錄，並在該目錄下記錄checkpoint資訊，斷點續傳成功後會刪除該目錄。如果指定了該選項，請確保指定的目錄可以被刪除。

      --encoding-type

      檔案名稱的編碼方式。取值為url。如果不指定該選項，則表示檔案名稱未經過編碼。

      --include

      包含符合指定條件的所有檔案。

      --exclude

      不包含任何符合指定條件的檔案。

      --meta

      設定檔案的中繼資料，格式為header:value#header:value，樣本為Cache-Control:no-cache#Content-Encoding:gzip。關於中繼資料的介紹，請參見set-meta（管理檔案中繼資料）。

      --acl

      檔案的讀寫權限ACL。取值如下：

      • default（預設值）：繼承Bucket的讀寫權限。

      • private：只有該Bucket的擁有者可以對該Bucket內的檔案進行讀寫操作，其他人無法訪問該Bucket內的檔案。

      • public-read：只有Bucket擁有者可以對該Bucket內的檔案進行寫操作，其他使用者（包括匿名訪問者）都可以對該Bucket中的檔案進行讀操作。這有可能造成您資料的外泄以及費用激增，如果被人惡意寫入違法資訊還可能會侵害您的合法權益。除特殊情境外，不建議您配置此許可權。

      • public-read-write：任何人（包括匿名訪問者）都可以對該Bucket內檔案進行讀寫操作。這有可能造成您資料的外泄以及費用激增，請謹慎操作。

      --disable-crc64

      關閉CRC64資料校正。預設情況下，ossutil進行資料轉送時都會開啟CRC64校正。

      --payer

      請求的支付方式。如果希望訪問指定路徑下的資源產生的流量、請求次數等費用由要求者支付，請將此選項的值設定為requester。

      -j，--jobs

      多檔案操作時的並發任務數，預設值為3，取值範圍為1~10000。

      --parallel

      單檔案操作時的並發任務數，取值範圍為1~10000。 如果不設定此選項，預設由ossutil根據操作類型和檔案大小自行決定。

      --version-id

      拷貝指定版本的檔案，僅支援在已開啟版本控制的Bucket內使用。

      --start-time

      Unix時間戳記。如果輸入這個選項，最後更新時間早於該時間的Object會被忽略。

      說明

      僅1.7.18及以上版本支援設定該參數。關於如何升級版本，請參見update（ossutil版本升級）。

      --end-time

      Unix時間戳記。如果使用該選項，則最後更新時間晚於通過此選項指定時間的Object會被忽略。

      說明

      • 如果同時指定了start-time和end-time，檔案的修改時間在start-time和end-time之間才會執行拷貝命令。

      • 僅1.7.18及以上版本支援設定該參數。關於如何升級版本，請參見update（ossutil版本升級）。

      關於此命令的其他通用選項，請參見通用選項。

      當預設並發數達不到使用者的效能要求時，可以調整-j，--jobs和--parallel選項來升降效能。預設情況下，ossutil根據檔案大小來計算parallel。當批量傳輸大檔案時，實際的並發數為jobs數乘以parallel數。

      • 若執行命令的ECS或伺服器的資源（網路、記憶體、CPU）有限，建議將並發數調低（如100以下）。如果資源未佔滿，可適當增加並發數。

      • 並發數過高可能因線程切換開銷和資源競爭導致效能下降，甚至引發EOF錯誤。請根據機器的實際資源狀況調整-j，--jobs和--parallel。進行效能壓測時，建議從較低的並發數開始，逐步增加以找到最佳值。

      使用樣本

      以下樣本均以 Linux 系統為例，請根據作業系統和實際環境修改參數。樣本環境假定：

      • 源Bucket：examplebucket1

      • 源Bucket指定目錄1：srcfolder1

      • 源Bucket指定目錄2：srcfolder2

      • 目標Bucket：examplebucket2

      • 目標Bucket指定目錄：desfolder

      拷貝單個檔案

      將檔案從一個目錄拷貝到同一Bucket的另一個目錄，並重新命名為 example.txt。

      ossutil cp oss://examplebucket1/srcfolder1/examplefile.txt oss://examplebucket1/srcfolder2/example.txt

      批量拷貝檔案

      拷貝檔案時，如果源路徑末尾沒有攜帶正斜線（/），則拷貝與指定首碼匹配的所有檔案到目標Bucket。如果源路徑末尾攜帶了正斜線（/），則僅拷貝指定目錄下的檔案拷到目標Bucket。

      假設源儲存空間examplebucket1指定目錄srcfolder1下包含以下檔案：

      srcfolder1/exampleobject1.txt
srcfolder1/exampleobject2.png
srcfolder1/dir1/
srcfolder1/dir1/exampleobject3.jpg
srcfolder1/dir2/
srcfolder1/dir2/exampleobject4.jpg

      • 拷貝時指定的源路徑不以正斜線（/）結尾

        ossutil cp oss://examplebucket1/srcfolder1  oss://examplebucket2 -r

        拷貝完成後，目標儲存空間examplebucket2下將新增以下檔案：

        srcfolder1/exampleobject1.txt
srcfolder1/exampleobject2.png
srcfolder1/dir1/
srcfolder1/dir1/exampleobject3.jpg
srcfolder1/dir2/
srcfolder1/dir2/exampleobject4.jpg

      • 拷貝時指定的源路徑以正斜線（/）結尾

        ossutil cp oss://examplebucket1/srcfolder1/  oss://examplebucket2 -r

        拷貝完成後，目標儲存空間examplebucket2下將新增以下檔案：

        exampleobject1.txt
exampleobject2.png
dir1/
dir1/exampleobject3.jpg
dir2/
dir2/exampleobject4.jpg

      • 拷貝增量檔案

        批量拷貝時，如果指定--update選項，只有當目標檔案不存在，或源檔案的最後修改時間晚於目標檔案時，ossutil才會執行拷貝操作。命令如下： 

        ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/path2/ -r --update

        該選項可用於當批量拷貝失敗重傳時，跳過已經拷貝成功的檔案，實現增量拷貝。

      • 僅拷貝目前的目錄下的檔案，忽略子目錄 

        ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder2/ --only-current-dir -r

      拷貝指定時間範圍檔案

      限定srcfolder1中檔案的修改時間，在北京時間2023年10月31日10:09:18至2023年10月31日12:55:58內時，檔案才會被拷貝。

      ossutil cp -r oss://examplebucket1/srcfolder1/ oss://examplebucket2/path2/ --start-time 1698718158 --end-time 1698728158

      拷貝符合指定條件的檔案

      使用--include和--exclude參數，在拷貝時選定合格檔案。

      • 拷貝所有檔案格式不為JPG的檔案 

        ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/desfolder/ --exclude "*.jpg" -r

      • 拷貝所有檔案名稱包含abc且不是JPG和TXT格式的檔案 

        ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket2/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

      拷貝並修改檔案元資訊

      使用--meta選項修改檔案的meta資訊，其內容格式為 header:value#header:value...。 

      ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/ --meta=Cache-Control:no-cache

      拷貝並指定要求者付費

      將一個檔案從源儲存空間（Bucket）複製到目標儲存空間，並指定要求者付費模式。

      ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/  --payer=requester

      拷貝並修改儲存類型

      可以在覆寫 檔案時，添加--meta選項來修改檔案儲存體類型。儲存類型可選值為：

      • Standard：標準儲存

      • IA：低頻訪問

      • Archive：Archive Storage

      • ColdArchive：冷Archive Storage

      • DeepColdArchive：深度冷Archive Storage

      關於儲存類型的更多資訊，請參見儲存類型。

      重要

      通過--meta選項修改儲存類型時，預設會覆蓋已有的自訂檔案中繼資料。 如果您希望修改儲存類型時保留已有的自訂檔案中繼資料，則需要利用x-oss-metadata-directive:COPY選項，先通過該選項保留已有的自訂檔案中繼資料，然後再進行檔案儲存體類型的修改。

      覆蓋已有的自訂檔案中繼資料

      • 將指定檔案的儲存類型修改為Archive Storage

        ossutil cp oss://examplebucket1/srcfolder1/examplefile.txt oss://examplebucket1/srcfolder1/examplefile.txt --meta X-oss-Storage-Class:Archive

      • 將指定檔案夾下所有檔案的儲存類型修改為標準儲存

        ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder1/ --meta X-oss-Storage-Class:Standard -r

      保留已有的自訂檔案中繼資料

      • 保留已有單個檔案的檔案中繼資料。

        ossutil cp oss://examplebucket1/srcfolder1/examplefile.txt oss://examplebucket1/srcfolder1/examplefile.txt --meta x-oss-metadata-directive:COPY

      • 保留已有多個檔案的中繼資料。

        ossutil cp oss://examplebucket1/srcfolder1/ oss://examplebucket1/srcfolder1/ --meta x-oss-metadata-directive:COPY -r -f
      重要

      • 通過cp修改檔案儲存體類型時，按Object源儲存類型收取Put類請求費用，並計量到目標Bucket。

      • 如果將Object轉換為低頻訪問、Archive Storage、冷Archive Storage或者深度冷Archive Storage類型，且儲存未滿指定周期，會產生儲存不足規定時間長度容量費用。更多資訊，請參見儲存費用。

      • 通過cp命令將Archive Storage、冷Archive Storage或者深度冷Archive Storage類型的Object轉換為標準、低頻訪問類型時，必須先通過restore（解凍檔案）命令解凍該Object，然後再使用cp命令轉換Object的儲存類型。如果開啟了歸檔直讀，Archive Storage類型Object無需解凍，就可以轉換儲存類型。

      • 通過cp命令對超過100 MB的檔案進行儲存類型轉換操作時，ossutil預設會根據檔案大小自行計算合適的分區大小值。如果自動切片無法滿足需求，您可以通過--part-size選項指定分區大小，但需確保分區數不能超過10000。

      拷貝並設定標籤

      在覆寫檔案時，添加--tagging選項修改檔案對象標籤，多個標籤以and（&）符號隔開。命令如下：

      ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/ --tagging "abc=1&bcd=2&……"

      關於對象標籤的更多資訊，請參見object-tagging（對象標籤）。

      拷貝並設定伺服器端加密

      可以在拷貝檔案時指定檔案的伺服器端加密方式，將檔案加密後儲存在Bucket內，關於伺服器端加密功能介紹的更多資訊，請參見伺服器端加密。

      • 拷貝檔案並指定加密方式為AES256 

        ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket1/srcfolder2/ --meta=x-oss-server-side-encryption:AES256

      • 拷貝檔案並指定加密方式為KMS 

        ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/ --meta=x-oss-server-side-encryption:KMS
        重要

        使用KMS加密時，OSS會在KMS平台上為這個檔案建立一個主要金鑰，會產生少量KMS密鑰API調用費用。更多資訊，請參見KMS計費標準。

      • 拷貝檔案並指定加密方式為KMS，指定CMK ID

        ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******

      恢複檔案的歷史版本

      開啟Bucket的版本控制後，針對資料的覆蓋和刪除操作將會以歷史版本的形式儲存下來。可以在cp命令中增加--version-id選項，將歷史版本覆寫為最新版本。

      首先，使用 ls --all-versions 命令擷取 Object 的所有版本 ID，再使用 --version-id 選項下載指定版本。

      說明

      --version-id選項僅支援在已開啟版本控制的Bucket內使用。開啟Bucket版本控制命令請參見bucket-versioning（版本控制）。

      ossutil cp oss://examplebucket1/examplefile.txt oss://examplebucket2/ --version-id  CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3MDRk

      跨帳號拷貝

      使用 -e, -i, -k 通用選項，將另一個阿里雲帳號下，華東2（上海）地區下源儲存空間examplebucket根目錄下的檔案srcobject.png拷貝至目標儲存空間destbucket。

      說明

      需要根據Bucket所在地區填寫對應的Endpoint。更多資訊，請參見地區和Endpoint。

      ossutil cp oss://examplebucket/srcobject.png  oss://destbucket  -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret
      安全提示：在命令列中直接使用AccessKey存在安全風險。對於自動化或長期任務，建議為源帳號建立RAM角色並授權給目標帳號使用，以實現更安全的跨帳號訪問。