C#调阿里云OSS核心是选对SDK版本并正确初始化Region和SignatureVersion：V1已停更，V2推荐但需.NET 5.0+，二者命名空间、构造方式、签名默认行为均不兼容，混用将导致编译或运行失败。
用 C# 调阿里云 OSS，核心就两点：选对 SDK 版本、初始化时别漏 Region 和 SignatureVersion。V1 SDK 仍广泛使用但已停止新功能迭代；V2 是当前推荐路径，但必须注意 .NET 运行时兼容性——OssClient 在 V2 中已被重构为异步优先的 OssClientV2，接口不兼容 V1。
确认你用的是 OSS C# SDK V2 还是 V1
V2 和 V1 的命名空间、构造方式、默认行为都不同，混用会直接编译失败或运行时报 MissingMethodException。V2 要求最低 .NET 5.0 或 .NET Standard 2.0，而 V1 支持 .NET Framework 4.5+，但官方明确标注“V1 不再维护”。
- 检查项目引用：V2 的 NuGet 包名是
Aliyun.OSS.SDK.NET（注意末尾无 V1/V2 后缀，但版本号 ≥ 2.0.0）；V1 是Aliyun.OSS.SDK - V2 初始化用
new OssClientV2(...)，V1 是new OssClient(...) - V2 默认启用 V4 签名且不可关闭；V1 需手动设置
conf.SignatureVersion = SignatureVersion.V4才能用 V4 - V2 的
PutObjectAsync等方法返回Task；V1 对应的是同步 + 异步两套 API（如PutObject和PutObjectAsync）
Endpoint、Region、SignatureVersion 必须三者齐备
只填 endpoint 和密钥，不设 region 或 SignatureVersion.V4，会导致 403 Forbidden 或 400 Bad Request，错误信息里常带 InvalidAccessKeyId 或 SignatureDoesNotMatch——这往往不是密钥错了，而是签名协议没对齐。
-
endpoint必须和 Bucket 所在地域严格匹配，例如杭州 Bucket 用https://oss-cn-hangzhou.aliyuncs.com，不能简写成https://oss.aliyuncs.com -
region是通用 Region ID（如cn-hangzhou），不是 endpoint 的子域名片段；它用于构造 V4 签名中的 scope，缺了或写错会签名失败 - V2 中
OssClientV2构造函数强制要求传入region参数；V1 中需额外调用client.SetRegion(region)，漏掉这句等于没设 - V1 若未设
conf.SignatureVersion = SignatureVersion.V4，默认走 V1 签名，而新创建的 RAM 用户默认禁用 V1 签名，直接拒绝请求
凭证不要硬编码，优先走环境变量或 IMDS
把 accessKeyId 和 accessKeySecret 写死在代码里，不仅违反最小权限原则，还会导致 Git 泄露风险。OSS SDK 支持多级凭证自动发现机制，按优先级依次尝试：
- 环境变量：
OSS_ACCESS_KEY_ID/OSS_ACCESS_KEY_SECRET（V1/V2 均支持） - V2 新增支持 ECS 实例元数据服务（IMDS）：当运行在阿里云 ECS 上时，可配置
OssClientV2Options.CredentialsProvider = new EcsRamRoleCredentialProvider("role-name") - V1 不支持 IMDS，只能靠环境变量或显式传入凭证
- 避免使用明文配置文件（如 appsettings.json）存 AKSK；若必须，确保该文件不在源码仓库中，且部署时通过 CI/CD 注入
ClientConfiguration 的关键参数取舍
V1 的 ClientConfiguration 和 V2 的 OssClientV2Options 都能调优连接行为，但默认值在高并发场景下容易成为瓶颈。
-
ConnectionLimit：V1 默认 512，V2 默认 100。如果批量上传 >100 个文件，建议设为 512 或更高，否则连接池耗尽会卡住请求 -
MaxErrorRetry：V1 默认 3，V2 默认 0（即不重试）。网络抖动时易失败，建议 V2 显式设为MaxErrorRetry = 3 -
EnableMD5Check：V1 默认 true，V2 默认 false。开启后上传下载会计算 MD5 校验，增加 CPU 开销约 10%~15%，但能防传输损坏；内网环境可关，公网建议开 -
ProxyHost：仅当应用跑在强制代理环境中才需配置；设了但代理不可达会导致所有请求超时，且错误日志不直观
Region 和 SignatureVersion 是初始化阶段最容易被忽略的两个点，尤其从 V1 迁移到 V2 时，SetRegion 调用变成构造函数必填参数，稍不注意就会卡在 403。另外，V2 的异步方法不提供同步阻塞包装，如果你在同步上下文（比如 ASP.NET Framework）里调用 GetAwaiter().GetResult()，可能引发死锁——这点文档很少提，但实际踩坑率很高。
