应使用 oss2 库而非 aliyun-python-sdk-oss，后者仅为底层 RPC 封装，oss2 支持断点续传、分片上传、进度回调等，安装需执行 pip install oss2，Endpoint 必须带 https 协议且与 bucket 地域严格匹配。
直接用 oss2 库，别碰 aliyun-python-sdk
aliyun-python-sdk-oss 是旧版 SDK，只提供底层 RPC 接口封装，不带文件上传/下载逻辑，连 put_object 都要手动拼 HTTP body 和签名。现在官方主推的是 oss2 —— 它是专为 OSS 设计的 Python SDK，内置断点续传、分片上传、进度回调、自动重试，开箱即用。
常见错误现象：aliyun-python-sdk-oss 装完后调用 OssClient.put_object 报 SignatureDoesNotMatch 或 InvalidArgument，本质是没处理 Content-MD5、Date header、CanonicalizedOSSHeaders 等签名要素。
- 安装正确依赖：
pip install oss2（不是aliyun-python-sdk-oss） - AccessKey 必须有
AliyunOSSFullAccess或最小权限策略（oss:PutObject+oss:GetObject） - Endpoint 不能写错：华东1（杭州）是
https://www.php.cn/link/116c87e094144d0002cff857e56a322f，不是http，也不是oss-cn-hangzhou.aliyuncs.com（缺协议头会静默失败）
上传单个本地文件到指定 bucket 和 path
核心就是初始化 oss2.Bucket，然后调用 put_object_from_file —— 它自动处理小文件直传、大文件分片、重试和异常。
import oss2
<p>auth = oss2.Auth('your-access-key-id', 'your-access-key-secret')
bucket = oss2.Bucket(auth, '<a href="https://www.php.cn/link/116c87e094144d0002cff857e56a322f">https://www.php.cn/link/116c87e094144d0002cff857e56a322f</a>', 'your-bucket-name')</p><h1>本地路径 → OSS 的 object key（注意：不带前导 /）</h1><p>result = bucket.put_object_from_file('remote/path/file.txt', '/local/path/file.txt')</p><p><span>立即学习</span>“<a href="https://pan.quark.cn/s/00968c3c2c15" style="text-decoration: underline !important; color: blue; font-weight: bolder;" rel="nofollow" target="_blank">Python免费学习笔记（深入）</a>”；</p><div class="aritcle_card flexRow">
<div class="artcardd flexRow">
<a class="aritcle_card_img" href="/xiazai/skill8054" title="python-parallelization"><img
src="https://img.php.cn/upload/skill/000/000/081/179181013081932.jpg" alt="python-parallelization" ></a>
<div class="aritcle_card_info flexColumn">
<a href="/xiazai/skill8054" title="python-parallelization">python-parallelization</a>
<p>将顺序 Python 代码转换为并行/并发实现，用于在需要并行化 Python 代码、提升性能时使用。</p>
</div>
<a href="/xiazai/skill8054" title="python-parallelization" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a>
</div>
</div><p>print(f'ETag: {result.etag}, HTTP status: {result.status}')
-
put_object_from_file第一个参数是 OSS 内部路径（object key），第二个是本地绝对或相对路径 - 如果本地路径含中文，确保 Python 文件本身用 UTF-8 编码，且系统 locale 支持（Linux/macOS 一般没问题，Windows 命令行需
chcp 65001） - 默认超时 60 秒，大文件可加参数：
put_object_from_file(..., progress_callback=callback)+ 自定义函数
同步整个本地目录（非增量，慎用）
oss2 不提供 rsync 式增量同步命令，但可用 os.walk + put_object_from_file 手动遍历实现“覆盖式同步”。注意：它不会删除 OSS 上多余文件，也不会跳过未修改文件。
容易踩的坑：os.walk 返回的 root 是相对路径，拼接 object key 时容易多出 ./ 或漏掉层级；同时忽略 .git、__pycache__ 等目录需显式过滤。
- 推荐先用
bucket.head_object(key)检查是否存在，再比对本地 mtime 和 OSSlast_modified（需开启 bucket 版本控制或自己存 checksum）才能做真正增量 - 简单覆盖同步示例中，object key 应用
os.path.relpath(os.path.join(root, file), local_dir)计算，避免硬编码路径分隔符 - 并发上传建议用
concurrent.futures.ThreadPoolExecutor，但线程数别超过 10，否则触发 OSS QPS 限流（默认 1000 QPS/bucket）
报错 InvalidBucketName 或 NoSuchBucket 怎么查
不是密钥错，而是 bucket 名称或 region 错了。OSS bucket 全局唯一，且创建后不能跨 region 访问。
- 确认 bucket 确实存在：登录阿里云控制台 → 对象存储 OSS → 查看“Bucket 名称”和“地域”
- Endpoint 必须与 bucket 所在地域严格匹配，例如华北2（北京）对应
https://oss-cn-beijing.aliyuncs.com，写成oss-cn-hangzhou就会报NoSuchBucket - bucket 名称不能含下划线
_、大写字母、连续短横线，且长度 3–63 字符 —— 错误名称会直接被oss2拒绝初始化，抛InvalidBucketName - 若用子账号 AccessKey，检查 RAM 策略是否显式允许该 bucket，如
"Resource": ["acs:oss:*:*:your-bucket-name/*"]
最常被忽略的是 Endpoint 协议和地域绑定——写错一个字符，错误信息就毫无提示地变成网络超时或 403，而不是明确的地域不匹配提示。
