.NET Web API接收IFormFile集合时参数始终为null的问题

安全阿岳

2026-6-17

解决.NET Web API集合类型接收IFormFile为null的问题

核心问题原因

当使用IList<IFormFile>、IEnumerable<IFormFile>等集合类型作为[FromForm]参数时，参数始终为null的核心原因是前端上传文件的表单字段名与接口参数名不匹配，或是最小API的绑定机制对直接的集合参数识别存在兼容性问题。

解决方案

1. 确保前端表单字段名与参数名完全一致

不管使用哪种集合类型，前端（Postman/Swagger）上传文件时，所有文件的表单键必须设置为与接口参数名相同的值（示例中为files），不能使用file、files[0]、files[1]这类带索引或不同名称的键：

Postman操作：选择form-data格式，添加多个文件，每个文件的Key都填写files
Swagger UI操作：点击Try it out后，在files字段处点击"Add item"添加多个文件，Swagger会自动使用正确的字段名提交

2. 使用DTO类包装集合（更可靠的方式）

针对最小API的绑定特性，将IFormFile集合包装到一个DTO类中，能避免直接使用集合类型可能出现的绑定问题，同时让接口定义更清晰：

// 定义上传文件的DTO
public class UploadFilesRequest
{
    public IList<IFormFile> Files { get; set; } = new List<IFormFile>();
}

public class Images : EndpointGroupBase
{
    public override void Map(WebApplication app)
    {
        app.MapGroup(this)
            .DisableAntiforgery()
            .RequireAuthorization()
            .MapPost(CreateImages);
    }

    public async Task<IResult> CreateImages(ISender sender, [FromForm] UploadFilesRequest request)
    {
        return Results.Ok(await sender.Send(new CreateImagesCommand(request.Files)));
    }
}