全部产品
Search

搜索本产品

    对象存储 OSS：cp（拷贝文件）

    文档中心

    对象存储 OSS：cp（拷贝文件）

    更新时间：Nov 05, 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：归档存储

      • ColdArchive：冷归档存储

      • DeepColdArchive：深度冷归档存储

      关于存储类型的更多信息，请参见存储类型。

      重要

      通过--meta选项修改存储类型时，默认会覆盖已有的自定义文件元数据。 如果您希望修改存储类型时保留已有的自定义文件元数据，则需要利用x-oss-metadata-directive:COPY选项，先通过该选项保留已有的自定义文件元数据，然后再进行文件存储类型的修改。

      覆盖已有的自定义文件元数据

      • 将指定文件的存储类型修改为归档存储

        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转换为低频访问、归档存储、冷归档存储或者深度冷归档存储类型，且存储未满指定周期，会产生存储不足规定时长容量费用。更多信息，请参见存储费用。

      • 通过cp命令将归档存储、冷归档存储或者深度冷归档存储类型的Object转换为标准、低频访问类型时，必须先通过restore（解冻文件）命令解冻该Object，然后再使用cp命令转换Object的存储类型。如果开启了归档直读，归档存储类型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角色并授权给目标账号使用，以实现更安全的跨账号访问。