阿里云 OSS 自带 Web 控制台，但凡涉及批量上传、断点续传、跨地域同步，鼠标点几下就显得力不从心——这种场景下
ossutil几乎是唯一选择。
ossutil 是 OSS 官方命令行工具，跨平台单二进制发行，没有 Python/Java 运行时依赖，CI/CD 流水线里直接 curl 拉下来就能用。2026 年官方主推 ossutil 2.0，最新稳定版迭代到 2.3.x，与 1.0 的差别比单纯版本号要大得多：底层签名升到 V4 强制要求 region、命令树彻底重构、连二进制名都从 ossutil64 改成了 ossutil。这些变化在动手前都值得过一遍。
安装与初始化配置
v2 的安装包按 OS × 架构组合发布在 gosspublic.alicdn.com/ossutil/v2/<版本>/ 下。Linux 与 macOS 一般直接 curl 拉 zip 解压，把可执行文件丢进 /usr/local/bin/；Windows 解压后把目录加进 Path 环境变量。装完跑 ossutil version 确认能调起来，老脚本里如果还写着 ossutil64，要么改名、要么先建个符号链接过渡再批量替换。
初始化走 ossutil config 进交互向导，依次问 Endpoint、Region、AccessKey ID、AccessKey Secret、可选的 STSToken。v2 把 region 提到必填位置是因为底层签名算法升到了 V4——这一步偷懒置空，会在第一次实际操作时被 InvalidArgument 直接打回来。Endpoint 可以不填，给了 region 之后默认走 oss-<region>.aliyuncs.com 的公网域名；同地域内网访问要手动写成 oss-<region>-internal.aliyuncs.com，省下来的是真金白银的公网带宽费。
配置文件默认落在 ~/.ossutilconfig，是 INI 格式，按 section 分多个 profile。日常单账号够用，但凡涉及”测试 bucket 与生产 bucket 在不同账号下”或”国内 + 海外两套 AK”的场景，多 profile 就成刚需，用 --profile <name> 切换比改环境变量优雅得多。配置优先级从高到低是命令行参数（-i/-k/-e）→ 环境变量（OSS_ACCESS_KEY_ID 等）→ 配置文件，CI 脚本一般用环境变量注入，本地交互式操作用配置文件。
不要把 AccessKey 写进命令行
ossutil -i AK -k SK ls oss://...这种写法虽然能跑，但 shell history、CI 日志、ps输出都会留底。生产凭证只走环境变量或配置文件，临时调试可以用--profile切到只读的子账号身份，比图省事更安全。
日常操作：cp / ls / rm / mv
通用语法是 ossutil <命令> <源> <目的>，OSS 路径以 oss://bucket/key 形式表达，本地路径可相对可绝对。贯穿所有命令的三个旗标是 -r（递归，处理目录必带）、-f（跳过覆盖确认，脚本里几乎必带）、-u（增量模式，按修改时间和大小判断要不要重传）。多线程靠 -j N 控制并发数，默认 5，传大文件夹时拉到 16 甚至 32 都没问题，瓶颈一般是出口带宽不是 CPU。
列举操作里，ossutil ls 不带参数列出当前账号所有 bucket，ossutil ls oss://my-bucket 列对象，带前缀的 ossutil ls oss://my-bucket/logs/ 等价于 prefix 查询。看单个对象的元信息用 ossutil stat oss://bucket/key，能拿到 size、ETag、storage class、修改时间，排查”为啥这个文件下载下来不对”经常从这一步开始。
上传下载都是 cp，方向完全由路径决定：
ossutil cp ./local-dir oss://my-bucket/backup/ -rf -j 16 # 上传整目录
ossutil cp oss://my-bucket/backup/ ./local-dir -rf -j 16 # 反过来下载
ossutil cp oss://src-bucket/a.zip oss://dst-bucket/b.zip # OSS 之间直接拷贝，不落本地OSS 之间的拷贝走内部网络，速度比”先下载再上传”快一两个数量级，跨账号迁移时尤其香。删除用 rm，-r 递归、-f 跳过确认，ossutil rm -rf oss://bucket/path/ 直接清掉整个前缀下的对象——这条命令没有回收站，跑之前一定再确认一遍 path 后缀的斜杠位置。mv 在 OSS 里本质上是 server-side copy + delete，没有真正的”移动”原语，对超大对象会瞬时计费两份存储，但耗时只取决于 metadata 操作，不需要重传数据。
sync：v2 真正值得用的新命令
老版本里”增量上传同步”是靠 cp -ru 模拟的，对比逻辑只看修改时间，删源不删目的端。v2 引入了独立的 sync 命令，行为更接近 rsync，把双向状态对齐做成了一等公民：
ossutil sync ./local-dir oss://my-bucket/backup/ --delete -j 16 # 镜像同步，目的端多余对象会被删
ossutil sync oss://src/ oss://dst/ --snapshot-path ./snap.db # 用本地快照加速二次同步--delete 让目的端镜像源端，多余对象会被删除——这是 cp -ru 做不到的。--snapshot-path 把上一次同步的状态写进本地快照文件，第二次跑时直接对比快照而不是回查 OSS，对象量大的目录能省下大量 list 请求成本。大文件超过 100 MB 自动走断点续传，checkpoint 存在 .ossutil_checkpoint/ 目录，跑一半被 Ctrl+C 掐掉，重跑就从中断点继续，不会从头再来。
性能调优的关键是分清 --job 和 --parallel：前者控制同时处理多少个对象，后者控制单个大文件的分片并发。海量小文件场景把 --job 调高（32-64），少量大文件场景把 --parallel 调高（16+），混合场景两个都拉满。带宽打不满之前，瓶颈往往就在这两个数值上而不是网络本身。
单次同步上限
带
--delete的 sync 单次最多处理 100 万个对象，超过会报over max sync numbers 1000000。超大目录要按前缀分批跑，或者改走 OSS 服务端的批量操作 API。
v2 的其他几项新能力
命令树拆成了高级命令（cp/ls/rm/sync 这些贴近用户意图的封装）和 API 级命令（ossutil api put-bucket-acl、ossutil api get-object-meta 这类直通底层 REST API 的形式）。前者用着舒服但抽象掉了细节，后者参数与官方 API 文档一一对应，写跨语言迁移脚本、或者排查”高级命令为啥这么响应”时更可控。辅助命令则覆盖配置文件管理、版本检查这些杂事。
--output-format json / yaml / xml 能把任意命令的输出切到结构化格式，配合 --output-query 像 JMESPath 一样筛字段，几乎不用再起 awk/grep 拼管道：
ossutil ls oss://my-bucket --output-format json \
--output-query "objects[?size > '1048576'].{key:key, size:size}"过滤器也是 v2 的发力点，cp/ls/rm 全都支持 --include/--exclude 通配，还能按大小、按修改时间、按对象元数据筛。“删掉超过 30 天没访问过、且大于 100 MB 的 log 文件”这种过去要写小脚本的需求，现在一条命令就能表达。--dry-run 在 v2 也是一等公民，所有写操作都能空跑一遍看影响范围，配合 --output-format json 还能把”将要发生什么”序列化下来当审计日志，生产环境第一次跑 --delete 同步之前过一遍 --dry-run 永远不亏。
返回码也做了标准化，非零返回码按出错阶段编码，CI 脚本里据此分支处理比 grep stderr 文本可靠得多。客户端时钟与服务端偏差超过 15 分钟时会触发 RequestTimeTooSkewed，v2 检测到后会自动校时再重试，这对 CI runner 这种 clock 经常飘的环境算是一个隐形的好处。
几个容易踩的点
OSS 路径区分大小写：oss://bucket/Photo.jpg 和 oss://bucket/photo.jpg 是两个对象，从 Linux 大小写敏感文件系统迁移的数据要特别小心，从 Windows 上传则反过来可能在源端就把大小写信息丢了。路径里不需要引号，但目录写法要带斜杠——oss://bucket/dir 是个对象 key，oss://bucket/dir/ 才是前缀，这对 ls 列出来的结果和 rm -r 的删除范围都有决定性影响。
v1 二进制名带 64 后缀，v2 改成了平台无关的 ossutil，老脚本升级时别只换版本不换命令名，否则一跑就是 command not found。Region 必填这点在第一次切到 v2 时是最常见的卡点，新建 bucket 时把所在地域记下来，配置时一次填好，省得后面每条命令都报签名错误。
ossutil config # 进配置向导
ossutil ls oss://bucket # 列对象
ossutil cp ./dir oss://bucket/ -rf -j 16 # 上传目录
ossutil cp oss://bucket/ ./dir -rf -j 16 # 下载目录
ossutil sync ./dir oss://bucket/ --delete # 双向同步（镜像）
ossutil rm oss://bucket/path/ -rf # 递归删除前缀
ossutil stat oss://bucket/key # 查对象元信息日常 80% 的工作量都在 cp、ls、rm、sync 四个命令上，记住 -r/-f/-u/-j 四个旗标和 --profile 切账号，剩下的复杂度在 ossutil --help 与 ossutil <cmd> --help 里现查现用即可。