2026 年阿里云对象存储OSS超详细教程：功能全解与一步一步上手流程（新手小白也能立刻上手）

Install-Package Aliyun.OSS.SDK.NetCore

using Aliyun.OSS;
using System;

class OSSExample
{
    private static string accessKeyId = "你的AccessKeyId";
    private static string accessKeySecret = "你的AccessKeySecret";
    private static string endpoint = "http://oss-cn-hangzhou.aliyuncs.com"; // 区域Endpoint，根据实际情况修改
    private static string bucketName = "你的bucket名称";

    static void Main(string[] args)
    {
        var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
        Console.WriteLine("客户端初始化成功！");
    }
}

OssClient client = new OssClient(endpoint, accessKeyId, accessKeySecret);

 /// <summary>
 /// 上传本地文件到阿里云OSS
 /// </summary>
 /// <param name="localFilePath">本地文件完整路径</param>
 /// <param name="ossObjectName">OSS中存储的文件路径+名称（如：hnt/20221227171528.jpg）</param>
 /// <exception cref="ArgumentNullException">参数为空时抛出</exception>
 /// <exception cref="FileNotFoundException">本地文件不存在时抛出</exception>
 public void UploadFileToOss(string localFilePath, string ossObjectName)
 {
     // 入参合法性校验
     if (string.IsNullOrWhiteSpace(localFilePath))
         throw new ArgumentNullException(nameof(localFilePath), "本地文件路径不能为空");
     if (string.IsNullOrWhiteSpace(ossObjectName))
         throw new ArgumentNullException(nameof(ossObjectName), "OSS对象名称不能为空");
     if (!File.Exists(localFilePath))
         throw new FileNotFoundException("本地文件不存在", localFilePath);

     try
     {
         // 创建客户端并执行上传
         var client = CreateOssClient();
         client.PutObject(bucketName, ossObjectName, localFilePath);
         Console.WriteLine($"文件上传成功！OSS路径：{ossObjectName}");
     }
     catch (OssException ex)
     {
         // 捕获OSS专属异常（含错误码），便于定位问题
         Console.WriteLine($"OSS上传异常：错误码={ex.ErrorCode}，错误信息={ex.Message}");
         throw; // 抛出异常让上层处理
     }
     catch (Exception ex)
     {
         Console.WriteLine($"文件上传失败：{ex.Message}");
         throw;
     }
 }

/// <summary>
/// 从阿里云OSS下载文件到本地
/// </summary>
/// <param name="ossObjectName">OSS中的文件路径+名称</param>
/// <param name="localSavePath">本地保存的完整路径</param>
/// <exception cref="ArgumentNullException">参数为空时抛出</exception>
public void DownloadFileFromOss(string ossObjectName, string localSavePath)
{
    // 入参合法性校验
    if (string.IsNullOrWhiteSpace(ossObjectName))
        throw new ArgumentNullException(nameof(ossObjectName), "OSS对象名称不能为空");
    if (string.IsNullOrWhiteSpace(localSavePath))
        throw new ArgumentNullException(nameof(localSavePath), "本地保存路径不能为空");

    try
    {
        var client = CreateOssClient();
        // 自动创建下载目录（避免目录不存在导致失败）
        string saveDirectory = Path.GetDirectoryName(localSavePath);
        if (!string.IsNullOrEmpty(saveDirectory) && !Directory.Exists(saveDirectory))
        {
            Directory.CreateDirectory(saveDirectory);
        }

        // 构建下载请求并写入本地文件流
        var getRequest = new GetObjectRequest(bucketName, ossObjectName);
        using (var localFileStream = File.OpenWrite(localSavePath))
        {
            client.GetObject(getRequest, localFileStream);
        }

        Console.WriteLine($"文件下载成功！本地路径：{localSavePath}");
    }
    catch (OssException ex)
    {
        Console.WriteLine($"OSS下载异常：错误码={ex.ErrorCode}，错误信息={ex.Message}");
        throw;
    }
    catch (Exception ex)
    {
        Console.WriteLine($"文件下载失败：{ex.Message}");
        throw;
    }
}

/// <summary>
/// 删除阿里云OSS中的指定文件
/// </summary>
/// <param name="ossObjectName">OSS中的文件路径+名称</param>
/// <exception cref="ArgumentNullException">参数为空时抛出</exception>
public void DeleteFileFromOss(string ossObjectName)
{
    if (string.IsNullOrWhiteSpace(ossObjectName))
        throw new ArgumentNullException(nameof(ossObjectName), "OSS对象名称不能为空");

    try
    {
        var client = CreateOssClient();
        client.DeleteObject(bucketName, ossObjectName);
        Console.WriteLine($"文件删除成功！OSS路径：{ossObjectName}");
    }
    catch (OssException ex)
    {
        Console.WriteLine($"OSS删除异常：错误码={ex.ErrorCode}，错误信息={ex.Message}");
        throw;
    }
    catch (Exception ex)
    {
        Console.WriteLine($"文件删除失败：{ex.Message}");
        throw;
    }
}

/// <summary>
/// 获取OSS指定前缀（目录）下的文件列表
/// </summary>
/// <param name="prefix">文件前缀/目录名（如：hnt/，空则查询整个Bucket）</param>
/// <param name="isRecursive">是否递归查询子目录（true=递归，false=仅当前目录）</param>
/// <param name="maxKeys">返回的最大文件数量（默认1000，最大不超过1000）</param>
/// <returns>文件名称列表（完整OSS路径）</returns>
/// <exception cref="ArgumentOutOfRangeException">maxKeys≤0或>1000时抛出</exception>
public List<string> ListFilesInOss(string prefix = "", bool isRecursive = false, int maxKeys = 1000)
{
    // 入参校验：maxKeys需在1-1000之间（OSS接口限制）
    if (maxKeys <= 0 || maxKeys > 1000)
        throw new ArgumentOutOfRangeException(nameof(maxKeys), "最大返回数量需在1-1000之间");

    try
    {
        var client = CreateOssClient();
        var listRequest = new ListObjectsRequest(bucketName)
        {
            Prefix = prefix ?? "",          // 前缀（目录），为空则查全部
            Delimiter = isRecursive ? null : "/", // 非递归时用/分隔目录，仅返回当前层级
            MaxKeys = maxKeys               // 最大返回数量
        };

        // 执行列表查询
        var listResult = client.ListObjects(listRequest);
        var fileList = new List<string>();

        // 遍历结果，收集文件名称（排除目录占位符）
        foreach (var objectSummary in listResult.ObjectSummaries)
        {
            // 过滤掉目录本身（以/结尾的是目录，不是文件）
            if (!objectSummary.Key.EndsWith("/"))
            {
                fileList.Add(objectSummary.Key);
            }
        }

        Console.WriteLine($"获取文件列表成功！前缀：{prefix}，数量：{fileList.Count}");
        return fileList;
    }
    catch (OssException ex)
    {
        Console.WriteLine($"OSS获取列表异常：错误码={ex.ErrorCode}，错误信息={ex.Message}");
        throw;
    }
    catch (Exception ex)
    {
        Console.WriteLine($"获取文件列表失败：{ex.Message}");
        throw;
    }
}