C#怎么实现文件下载接口？ASP.NET Core文件下载方法有哪些？

在ASP.NET Core项目中，文件下载接口是非常常用的功能模块，不管是提供用户资料下载、导出报表文件还是分发静态资源，都需要用到文件下载的相关实现。C#提供了多种内置的文件返回方式，开发者可以根据不同的业务场景选择合适的实现方案。

基础文件下载实现方式

1. 返回物理文件（PhysicalFile）

如果文件已经存储在服务器的物理路径中，可以直接使用PhysicalFile方法返回文件，这是最简单的文件下载实现方式。

using Microsoft.AspNetCore.Mvc;

namespace FileDownloadDemo.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class FileController : ControllerBase
    {
        /// <summary>
        /// 下载服务器物理路径下的文件
        /// </summary>
        /// <returns>文件结果</returns>
        [HttpGet("download-physical")]
        public IActionResult DownloadPhysicalFile()
        {
            // 服务器上文件的绝对路径
            string filePath = @"D:filestest.pdf";
            // 下载时显示的文件名
            string downloadFileName = "用户手册.pdf";
            // 判断文件是否存在
            if (!System.IO.File.Exists(filePath))
            {
                return NotFound("请求的文件不存在");
            }
            // 返回物理文件，指定内容类型为application/octet-stream（通用二进制流）
            return PhysicalFile(filePath, "application/octet-stream", downloadFileName);
        }
    }
}

2. 返回流文件（FileStreamResult）

如果文件是从其他渠道获取的流（比如从云存储读取、数据库读取的二进制流），可以使用FileStreamResult返回流数据实现下载。

using Microsoft.AspNetCore.Mvc;
using System.IO;

namespace FileDownloadDemo.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class FileController : ControllerBase
    {
        /// <summary>
        /// 通过流的方式返回文件下载
        /// </summary>
        /// <returns>文件结果</returns>
        [HttpGet("download-stream")]
        public IActionResult DownloadStreamFile()
        {
            string filePath = @"D:filestest.png";
            string downloadFileName = "示例图片.png";
            if (!System.IO.File.Exists(filePath))
            {
                return NotFound("请求的文件不存在");
            }
            // 创建文件流
            FileStream fileStream = new FileStream(filePath, FileMode.Open, FileAccess.Read);
            // 返回流文件结果
            return File(fileStream, "application/octet-stream", downloadFileName);
        }
    }
}

3. 返回字节数组（FileContentResult）

当文件内容已经被读取为字节数组时，可以使用FileContentResult直接返回字节数组实现下载。

using Microsoft.AspNetCore.Mvc;

namespace FileDownloadDemo.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class FileController : ControllerBase
    {
        /// <summary>
        /// 通过字节数组返回文件下载
        /// </summary>
        /// <returns>文件结果</returns>
        [HttpGet("download-bytes")]
        public IActionResult DownloadBytesFile()
        {
            string filePath = @"D:filestest.txt";
            string downloadFileName = "说明文档.txt";
            if (!System.IO.File.Exists(filePath))
            {
                return NotFound("请求的文件不存在");
            }
            // 读取文件为字节数组
            byte[] fileBytes = System.IO.File.ReadAllBytes(filePath);
            // 返回字节数组文件结果
            return File(fileBytes, "application/octet-stream", downloadFileName);
        }
    }
}

实战进阶技巧

大文件分段下载支持

对于大文件下载，建议支持分段下载，避免一次性加载整个文件到内存导致服务压力过大，ASP.NET Core默认已经支持部分请求（Range请求），只需要保证返回的文件结果支持分段即可。

using Microsoft.AspNetCore.Mvc;

namespace FileDownloadDemo.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class FileController : ControllerBase
    {
        /// <summary>
        /// 支持大文件分段下载
        /// </summary>
        /// <returns>文件结果</returns>
        [HttpGet("download-large")]
        public IActionResult DownloadLargeFile()
        {
            string filePath = @"D:fileslarge-video.mp4";
            string downloadFileName = "演示视频.mp4";
            if (!System.IO.File.Exists(filePath))
            {
                return NotFound("请求的文件不存在");
            }
            // 启用分段下载支持，默认PhysicalFile已经支持Range请求
            Response.Headers.Add("Accept-Ranges", "bytes");
            return PhysicalFile(filePath, "video/mp4", downloadFileName);
        }
    }
}

添加下载权限校验

实际项目中文件下载通常需要校验用户权限，只有有权限的用户才能下载对应文件，可以在接口中添加权限判断逻辑。

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

namespace FileDownloadDemo.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class FileController : ControllerBase
    {
        /// <summary>
        /// 需要权限校验的文件下载接口
        /// </summary>
        /// <param name="fileId">文件ID</param>
        /// <returns>文件结果</returns>
        [HttpGet("download-auth")]
        // 添加授权特性，只有登录用户才能访问
        [Authorize]
        public IActionResult DownloadWithAuth(int fileId)
        {
            // 这里可以查询数据库校验当前用户是否有下载该文件的权限
            // 模拟权限校验逻辑
            bool hasPermission = CheckUserPermission(User.Identity.Name, fileId);
            if (!hasPermission)
            {
                return Forbid("你没有权限下载该文件");
            }
            string filePath = $@"D:files{fileId}.pdf";
            string downloadFileName = $"文件{fileId}.pdf";
            if (!System.IO.File.Exists(filePath))
            {
                return NotFound("请求的文件不存在");
            }
            return PhysicalFile(filePath, "application/octet-stream", downloadFileName);
        }

        /// <summary>
        /// 模拟权限校验方法
        /// </summary>
        private bool CheckUserPermission(string userName, int fileId)
        {
            // 实际项目中这里可以查询数据库或者权限系统判断
            return !string.IsNullOrEmpty(userName) && fileId > 0;
        }
    }
}

常见内容类型对照表

设置正确的内容类型可以让浏览器正确识别文件类型，避免下载后出现文件无法打开的问题，以下是常见文件类型的内容类型对照：

如果不确定文件的内容类型，直接使用application/octet-stream作为通用二进制流类型即可，浏览器会自动将文件下载到本地。

C#ASP.NET_Core文件下载接口FileResult修改时间：2026-06-14 01:48:51