下载对象到本地文件（
download_file）。SDK 先查询对象大小，小文件直接下载，大文件按字节范围并发下载，并通过本地记录支持符合条件的断点续传。注意事项
操作的存储桶应处于 Available 状态；传输失败可能表现为服务端、客户端或本地文件异常，处理方式见 Python SDK 异常处理。
大小不超过
PartSize × 1024 × 1024 字节时直接下载；超过时走分块下载。分块大小至少为 1MB，并可能为满足 MaxPartCount 而增大。对象键末尾
/ 严格区分类型。源键类型不匹配按不存在处理，HTTP 404；HEAD 无错误正文时 SDK 错误码为 NoSuchResource。本页示例面向文件对象；读取目录请参见 Python SDK 下载对象。多次请求及续传期间必须保持源对象不变。高性能桶没有对象版本保护；本接口不提供下载快照，CRC 校验也不是条件读取或版本锁定。
续传需要保留下载记录和对应临时文件，并使用相同 Bucket、Key、目标绝对路径和记录目录重新调用。SDK 会核对源对象的 ETag、Last-Modified、Content-Length；记录不匹配或临时文件缺失时重新下载，不保证复用全部已下载内容。
默认记录目录为用户主目录下的
.cos_download_tmp_file；可用 DumpRecordDir 指定。记录目录与目标父目录需可写；请先创建目标父目录。同一目标文件不要同时运行多个下载任务。默认先写临时文件，再替换目标路径，已有同名本地文件可能被替换。
DisableTempDestFilePath=True 仅使直接下载分支直接写目标，失败可能留下部分内容；分块下载仍使用临时文件。EnableCRC=True 仅在分块下载路径执行最终 CRC64 校验，要求响应提供校验值。校验时会一次性将整个本地文件读入内存，增加内存和磁盘读取开销；校验发生在目标文件替换后，校验失败并不保证保留原目标文件。progress_callback(finished, total) 仅在分块路径调用；已恢复分块计入进度。小文件路径不执行此回调或高级 CRC 校验。进度满额不等于方法成功，必须等待正常返回。分块传输失败时保留记录和临时文件供重试；成功后移除记录。遇到 CRC 错误先停止使用目标文件，核对源对象并处理对应记录后重新下载，不要仅凭本地文件存在判断成功。
本接口用于完整对象下载，不传
Range 来下载局部内容；范围读取请使用 Python SDK 下载对象。传入 VersionId 会在本地报错。请求
方法原型
def download_file(self, Bucket, Key, DestFilePath, PartSize=20, MAXThread=5, EnableCRC=False,progress_callback=None, DumpRecordDir=None, KeySimplifyCheck=True,DisableTempDestFilePath=False, MaxPartCount=10000, **Kwargs)
参数说明
参数 | 说明 | 类型 | 是否必选 |
Bucket | 高性能桶完整名称，例如 examplebucket-x--1250000000 | string | 是 |
Key | 文件对象键，不以 / 结尾 | string | 是 |
DestFilePath | 本地目标文件路径，父目录需存在 | string | 是 |
PartSize | 直接下载阈值和分块大小，正整数，默认 20，单位 MB | int | 否 |
MAXThread | 分块并发线程数，正整数，默认 5 | int | 否 |
MaxPartCount | 分块下载最大分块数，正整数，默认 10000 | int | 否 |
EnableCRC | 分块下载完成后校验 CRC64，默认 False | bool | 否 |
progress_callback | 分块下载进度回调，默认 None | callable | 否 |
DumpRecordDir | 续传记录目录；不指定时使用上述默认目录 | string | 否 |
KeySimplifyCheck | 对象键安全检查，保持默认 True | bool | 否 |
DisableTempDestFilePath | 直接下载时是否直接写目标，建议保持默认 False | bool | 否 |
Kwargs | 可选参数请遵循本文；不传版本或范围参数 | dict | 否 |
响应
成功返回
None，内容写入 DestFilePath。发生异常时不要将目标文件视为已经完整下载并通过校验。错误码
实际案例
# -*- coding: utf-8 -*-import osfrom qcloud_cos import CosConfig, CosS3Client# 高性能桶经 VPC 内网 HTTP 80 端口接入，SDK 的网关 DNS 负载均衡也仅对 HTTP 请求生效；SDK 默认 https，此处需显式指定 http。config = CosConfig(Scheme='http', Region='ap-guangzhou',SecretId=os.environ['COS_SECRET_ID'],SecretKey=os.environ['COS_SECRET_KEY'],Token=os.environ.get('COS_SECURITY_TOKEN'),EnableRapidDomain=True)client = CosS3Client(config)bucket = 'examplebucket-x--1250000000'def progress(finished, total):print('processed bytes: %s / %s' % (finished, total))client.download_file(Bucket=bucket, Key='uploads/report.bin', DestFilePath='downloaded-report.bin',PartSize=8, MAXThread=4, EnableCRC=True,DumpRecordDir='./download-records', progress_callback=progress)print('download completed')# 只有分块路径执行上述高级 CRC 校验与进度回调。
