基于.NET Core的大文件分块上传实现方案

1. 项目背景与核心需求

在Web应用开发中，大文件上传一直是比较头疼的问题。特别是当用户需要上传整个文件夹时，传统的单文件上传方式往往会遇到各种限制和性能瓶颈。最近我在一个企业内部文档管理系统项目中，就遇到了需要支持用户批量上传文件夹的需求。

这个需求的核心痛点在于：

• 浏览器对单次HTTP请求有大小限制（通常2GB左右）
• 大文件上传容易因网络波动中断
• 服务器需要合理控制内存占用
• 用户需要实时了解上传进度

经过技术选型，我们最终决定采用.NET Core + 分块上传的方案来解决这个问题。下面我就详细分享这个方案的具体实现过程。

2. 技术方案设计

2.1 整体架构设计

整个上传流程分为三个主要部分：

1. 前端：使用JavaScript读取本地文件系统，将大文件分块
2. 传输层：通过HTTP协议分块上传
3. 后端：.NET Core接收分块并重组文件

code复制[前端] --> [分块] --> [上传] --> [.NET Core后端] --> [重组] --> [存储]

2.2 前端实现要点

前端需要完成以下几个关键任务：

• 通过<input type="file" webkitdirectory>获取文件夹内容
• 使用File API读取文件内容
• 实现分块逻辑（通常1-5MB/块）
• 管理上传队列和重试机制
• 显示上传进度

javascript复制// 获取文件夹内容示例
document.getElementById('folderInput').addEventListener('change', function(e) {
    const files = e.target.files;
    // 处理文件列表...
});

2.3 后端API设计

后端需要提供以下API端点：

1. /api/upload/init - 初始化上传会话
2. /api/upload/chunk - 上传分块
3. /api/upload/complete - 完成上传

每个请求都需要包含以下元数据：

• 文件唯一标识符
• 当前块序号
• 总块数
• 文件哈希（用于校验）

3. .NET Core后端实现

3.1 项目配置

首先创建一个新的ASP.NET Core Web API项目：

bash复制dotnet new webapi -n FileUploadDemo

添加必要的NuGet包：

bash复制dotnet add package Microsoft.AspNetCore.Http.Features

3.2 控制器实现

创建FileUploadController.cs：

csharp复制[ApiController]
[Route("api/[controller]")]
public class FileUploadController : ControllerBase
{
    private readonly IWebHostEnvironment _env;
    
    public FileUploadController(IWebHostEnvironment env)
    {
        _env = env;
    }
    
    [HttpPost("init")]
    public IActionResult InitUpload([FromBody] UploadInfo info)
    {
        // 验证并初始化上传会话
        // 返回上传令牌等元数据
    }
    
    [HttpPost("chunk")]
    public async Task<IActionResult> UploadChunk(IFormFile file, [FromForm] ChunkInfo info)
    {
        // 接收并存储分块
    }
    
    [HttpPost("complete")]
    public IActionResult CompleteUpload([FromBody] CompleteInfo info)
    {
        // 合并所有分块
        // 返回最终文件信息
    }
}

3.3 分块接收与存储

关键的分块接收逻辑：

csharp复制[HttpPost("chunk")]
public async Task<IActionResult> UploadChunk(IFormFile file, [FromForm] ChunkInfo info)
{
    var tempPath = Path.Combine(_env.ContentRootPath, "Temp");
    Directory.CreateDirectory(tempPath);
    
    var chunkPath = Path.Combine(tempPath, $"{info.FileId}.{info.ChunkNumber}");
    
    using (var stream = new FileStream(chunkPath, FileMode.Create))
    {
        await file.CopyToAsync(stream);
    }
    
    return Ok(new { info.ChunkNumber });
}

3.4 分块合并实现

当所有分块上传完成后，需要将它们合并为完整文件：

csharp复制private void MergeFileChunks(string fileId, string fileName, int totalChunks)
{
    var tempPath = Path.Combine(_env.ContentRootPath, "Temp");
    var finalPath = Path.Combine(_env.ContentRootPath, "Uploads", fileName);
    
    using (var finalStream = new FileStream(finalPath, FileMode.Create))
    {
        for (int i = 1; i <= totalChunks; i++)
        {
            var chunkPath = Path.Combine(tempPath, $"{fileId}.{i}");
            var chunkBytes = System.IO.File.ReadAllBytes(chunkPath);
            finalStream.Write(chunkBytes, 0, chunkBytes.Length);
            System.IO.File.Delete(chunkPath);
        }
    }
}

4. 前端完整实现

4.1 HTML结构

html复制<div class="upload-container">
    <input type="file" id="folderInput" webkitdirectory directory multiple>
    <button id="uploadBtn">开始上传</button>
    <div class="progress-container">
        <div class="progress-bar"></div>
        <div class="progress-text">0%</div>
    </div>
</div>

4.2 JavaScript实现

javascript复制class FolderUploader {
    constructor() {
        this.chunkSize = 2 * 1024 * 1024; // 2MB
        this.parallelUploads = 3;
        this.uploadQueue = [];
        this.activeUploads = 0;
    }
    
    async uploadFolder(files) {
        // 初始化上传会话
        const session = await this.initUploadSession(files);
        
        // 创建上传队列
        for (const file of files) {
            await this.prepareFileChunks(file, session);
        }
        
        // 开始上传
        this.processUploadQueue();
    }
    
    async prepareFileChunks(file, session) {
        const chunkCount = Math.ceil(file.size / this.chunkSize);
        
        for (let i = 0; i < chunkCount; i++) {
            const start = i * this.chunkSize;
            const end = Math.min(start + this.chunkSize, file.size);
            const chunk = file.slice(start, end);
            
            this.uploadQueue.push({
                file,
                chunk,
                chunkNumber: i + 1,
                totalChunks: chunkCount,
                sessionId: session.id
            });
        }
    }
    
    async processUploadQueue() {
        while (this.uploadQueue.length > 0 && this.activeUploads < this.parallelUploads) {
            const item = this.uploadQueue.shift();
            this.activeUploads++;
            
            try {
                await this.uploadChunk(item);
            } catch (error) {
                console.error('上传失败:', error);
                this.uploadQueue.unshift(item); // 重新加入队列
            } finally {
                this.activeUploads--;
                this.processUploadQueue();
            }
        }
    }
    
    async uploadChunk(item) {
        const formData = new FormData();
        formData.append('file', item.chunk, item.file.name);
        formData.append('fileId', item.sessionId + '_' + item.file.name);
        formData.append('chunkNumber', item.chunkNumber);
        formData.append('totalChunks', item.totalChunks);
        
        const response = await fetch('/api/upload/chunk', {
            method: 'POST',
            body: formData
        });
        
        if (!response.ok) {
            throw new Error('上传失败');
        }
        
        this.updateProgress(item);
    }
    
    updateProgress(item) {
        // 更新UI进度显示
    }
}

5. 高级功能与优化

5.1 断点续传实现

为了实现断点续传，我们需要在后端记录已接收的分块：

csharp复制[HttpPost("init")]
public IActionResult InitUpload([FromBody] UploadInfo info)
{
    var tempPath = Path.Combine(_env.ContentRootPath, "Temp");
    var filePattern = $"{info.FileId}.*";
    
    var existingChunks = Directory.GetFiles(tempPath, filePattern)
        .Select(f => int.Parse(Path.GetExtension(f).TrimStart('.')))
        .ToList();
    
    return Ok(new {
        existingChunks,
        // 其他元数据...
    });
}

前端可以根据返回的已存在分块列表跳过已经上传的部分。

5.2 上传速度优化

1. 并行上传：如前面代码所示，可以同时上传多个分块
2. 动态分块大小：根据网络状况调整分块大小
3. 压缩传输：在传输前对分块进行gzip压缩

javascript复制async function compressChunk(chunk) {
    const stream = chunk.stream();
    const compressedStream = stream.pipeThrough(new CompressionStream('gzip'));
    return await new Response(compressedStream).blob();
}

5.3 安全性考虑

1. 文件类型校验：限制可上传的文件类型
2. 大小限制：设置合理的总大小限制
3. 病毒扫描：集成病毒扫描服务
4. 权限控制：实现基于角色的访问控制

csharp复制private bool IsFileTypeAllowed(string fileName)
{
    var allowedExtensions = new[] { ".pdf", ".docx", ".xlsx" };
    var extension = Path.GetExtension(fileName).ToLower();
    return allowedExtensions.Contains(extension);
}

6. 常见问题与解决方案

6.1 分块上传失败处理

问题现象：某些分块上传失败导致整个文件无法合并

解决方案：

1. 实现自动重试机制（前端）
2. 记录失败的分块并在UI上提示
3. 提供手动重试单个分块的选项

javascript复制async function uploadWithRetry(item, maxRetries = 3) {
    let attempts = 0;
    while (attempts < maxRetries) {
        try {
            await uploadChunk(item);
            return;
        } catch (error) {
            attempts++;
            if (attempts >= maxRetries) throw error;
            await new Promise(resolve => setTimeout(resolve, 1000 * attempts));
        }
    }
}

6.2 内存占用过高

问题现象：上传大文件时服务器内存飙升

解决方案：

1. 使用流式处理而非缓冲整个文件
2. 限制并发上传数量
3. 增加服务器内存限制配置

csharp复制// 在Program.cs中配置
builder.WebHost.ConfigureKestrel(serverOptions => {
    serverOptions.Limits.MaxRequestBodySize = 1073741824; // 1GB
});

builder.Services.Configure<FormOptions>(x => {
    x.MultipartBodyLengthLimit = 1073741824; // 1GB
});

6.3 跨平台兼容性问题

问题现象：不同操作系统路径处理不一致

解决方案：

1. 使用Path.Combine代替字符串拼接
2. 统一使用正斜杠(/)
3. 处理文件名中的特殊字符

csharp复制var safeFileName = Path.GetInvalidFileNameChars()
    .Aggregate(fileName, (current, c) => current.Replace(c, '_'));

7. 部署与性能调优

7.1 服务器配置建议

1. IIS部署：

   • 增加上传限制：

     xml复制<system.webServer>
         <security>
             <requestFiltering>
                 <requestLimits maxAllowedContentLength="1073741824" />
             </requestFiltering>
         </security>
     </system.webServer>
     

2. Kestrel配置：

   csharp复制builder.WebHost.ConfigureKestrel(serverOptions => {
       serverOptions.Limits.MaxRequestBodySize = 1073741824; // 1GB
   });
   

7.2 数据库集成（可选）

如果需要记录上传历史，可以集成数据库：

csharp复制public class UploadRecord
{
    public int Id { get; set; }
    public string FileName { get; set; }
    public string FilePath { get; set; }
    public long FileSize { get; set; }
    public DateTime UploadTime { get; set; }
    public string UploadedBy { get; set; }
}

// 在控制器中注入DbContext
private readonly AppDbContext _context;

// 完成上传后保存记录
await _context.UploadRecords.AddAsync(new UploadRecord {
    FileName = fileName,
    FilePath = filePath,
    FileSize = new FileInfo(filePath).Length,
    UploadTime = DateTime.UtcNow,
    UploadedBy = User.Identity.Name
});
await _context.SaveChangesAsync();

7.3 负载均衡考虑

在多服务器环境下，需要考虑：

1. 使用共享存储（如Azure Blob Storage、AWS S3）
2. 或者使用粘性会话（sticky session）
3. 或者将分块暂存到数据库中

csharp复制// Azure Blob Storage示例
public async Task UploadToBlobStorage(Stream stream, string blobName)
{
    var blobServiceClient = new BlobServiceClient(connectionString);
    var containerClient = blobServiceClient.GetBlobContainerClient("uploads");
    var blobClient = containerClient.GetBlobClient(blobName);
    await blobClient.UploadAsync(stream, true);
}

8. 实际应用中的经验分享

在实际项目中实现这个方案时，我总结了以下几点经验：

1. 分块大小选择：经过测试，2-5MB的分块大小在大多数网络环境下表现最佳。太小的分块会增加HTTP请求开销，太大的分块则容易因网络波动失败。

2. 进度显示优化：不要每次分块上传完成都更新UI，这会导致界面卡顿。可以使用requestAnimationFrame来节流进度更新。

3. 内存管理：在处理超大文件时，一定要使用流式处理。我们曾经遇到过因为缓冲整个文件导致服务器内存溢出的问题。

4. 文件命名策略：使用GUID作为临时文件名前缀，避免文件名冲突。特别是当多个用户同时上传同名文件时。

5. 清理机制：实现一个后台服务定期清理未完成的上传临时文件，避免磁盘空间被占满。

6. 客户端验证：在上传前先在客户端检查文件大小和类型，可以节省带宽并提供即时反馈。

7. 日志记录：详细记录上传过程中的关键事件，这对排查问题非常有帮助。但要注意不要记录敏感信息。

8. 测试策略：特别要测试网络不稳定的情况，模拟慢速网络和中断恢复场景。我们使用Fiddler来模拟各种网络条件。