帮你快速理解、总结文档立即下载
文档中心>对象存储>高性能存储>SDK 文档>Python SDK>高级传输接口>上传本地文件

上传本地文件

最近更新时间：2026-10-21 18:34:06
我的收藏

本页目录：

上传本地文件（upload_file）。SDK 根据文件大小选择直接上传或分块上传，并在分块路径中尝试复用符合条件的未完成上传任务。调用会等待上传完成后返回，数据请求由 SDK 自动进行会话鉴权。

注意事项

操作的存储桶应处于 Available 状态；传输失败可能表现为服务端、客户端或本地文件异常，处理方式见 Python SDK 异常处理。
文件大小不超过 PartSize × 1024 × 1024 字节时直接上传，超过时分块上传。PartSize 为正整数，按每 MB 为 1024 × 1024 字节设置；分块不得超过 5GB，SDK 会在需要时调整分块大小以控制分块数。请为超大文件选取合适的分块大小。
本页用于上传文件对象。对象键末尾 / 严格区分文件和目录；创建目录请使用 Python SDK 上传对象 的空内容示例。文件不能覆盖同名目录。
需要防覆盖时，每次调用（包括失败后重试）均显式传入 ForbidOverwrite='true'。直接上传与最终完成分块上传都会携带本次防覆盖条件；已有同名目标时返回 409 FileAlreadyExists。
自动续传按桶和完整对象键查找未完成任务，校验已上传分块的大小和 ETag 后才复用；不满足条件时创建新任务。上传和重试期间请保持本地文件、对象键及分块配置不变，不要并发操作同一目标的上传任务。
续传复用任务初始化时的对象元数据；更改本次 ContentType 或 Metadata 不会重建已有任务的元数据。需要重新初始化时，先确认并终止相应的旧任务。
当前自动续传仅支持整数形式的已上传分块分页游标。遇到游标格式不兼容时，请核对未完成任务，必要时使用 Python SDK 列举已上传分块 与手动分块接口原样回传游标。
分块失败或 Complete 失败不会在本接口中自动终止上传任务。需要放弃时，先 Python SDK 列举分块上传，确认目标 Key 和 UploadId，再 Python SDK 终止分块上传。响应丢失时先核对最终对象状态。
progress_callback(finished, total) 接收累计处理字节数和文件总字节数，仅分块路径调用；续传跳过的已完成分块也计入进度。回调应简短且不抛异常；进度达到总量不等于 Complete 已成功，以方法正常返回为准。
高性能桶不支持对象版本与服务端回调，传入 VersionId、Callback、CallbackVar 会在本地报错。

请求

方法原型

def upload_file(self, Bucket, Key, LocalFilePath, PartSize=1, MAXThread=5, EnableMD5=False,
                progress_callback=None, **kwargs)

参数说明

参数
说明
类型
是否必选
Bucket
高性能桶完整名称，例如 examplebucket-x--1250000000
string
是
Key
文件对象键，不以 / 结尾
string
是
LocalFilePath
可读取的本地文件路径
string
是
PartSize
分块大小及直接上传阈值，默认 1，单位 MB
int
否
MAXThread
分块上传并发线程数，正整数，默认 5
int
否
EnableMD5
计算并发送 Content-MD5，直接上传及新上传分块均适用，默认 False
bool
否
progress_callback
本地进度回调，仅分块路径调用，默认 None
callable
否
ForbidOverwrite
关键字参数；仅字符串 "true" / "false"，省略允许覆盖文件
string
否
ContentType / Metadata
文件内容类型与自定义元数据；Metadata 键以 x-cos-meta- 开头
string / dict
否
kwargs
可选请求参数，使用本文列出的参数
dict
否

响应

返回字典。直接上传返回响应头，分块上传返回完成请求的响应头及结果字段；可读取 ETag。分块对象的 ETag 不应当作完整文件内容的 MD5。

错误码

本接口遵循统一的错误响应和错误码，详情请参见 错误码文档。

实际案例

# -*- coding: utf-8 -*-
import os
from 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))

# 使用已存在的本地文件；重试时保留相同配置和 ForbidOverwrite。
result = client.upload_file(
    Bucket=bucket, Key='uploads/report.bin', LocalFilePath='report.bin',
    PartSize=8, MAXThread=4, EnableMD5=True,
    progress_callback=progress, ForbidOverwrite='true')
print('upload completed, ETag: %s' % result['ETag'])

中国站