Blazor如何实现从服务器下载文件到客户端

Blazor作为基于.NET的前端框架，支持服务端和WebAssembly两种托管模式，两种模式下从服务器下载文件到客户端的实现逻辑存在差异，需要根据实际项目场景选择合适的方案。

后端文件接口实现

无论哪种Blazor模式，都需要先在后端提供文件下载的接口，我们可以基于ASP.NET Core的控制器实现文件返回逻辑。以下是一个通用的文件下载接口示例，支持返回任意类型的文件：

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

[ApiController]
[Route("api/[controller]")]
public class FileController : ControllerBase
{
    // 文件下载接口，接收文件路径参数
    [HttpGet("download")]
    public IActionResult DownloadFile(string filePath)
    {
        // 校验文件是否存在
        if (!System.IO.File.Exists(filePath))
        {
            return NotFound("文件不存在");
        }
        // 读取文件字节流
        var fileBytes = System.IO.File.ReadAllBytes(filePath);
        // 获取文件名称
        var fileName = Path.GetFileName(filePath);
        // 返回文件，指定内容类型和下载文件名
        return File(fileBytes, "application/octet-stream", fileName);
    }
}

Blazor WebAssembly模式下载文件

Blazor WebAssembly运行在浏览器沙箱中，无法直接操作本地文件系统，需要通过JavaScript互操作实现文件下载。首先需要在项目中添加JavaScript函数，用于触发浏览器下载行为：

// 定义在wwwroot下的JS文件中
function downloadFileFromStream(fileName, contentStream) {
    const arrayBuffer = await contentStream.arrayBuffer();
    const blob = new Blob([arrayBuffer]);
    const url = URL.createObjectURL(blob);
    const anchorElement = document.createElement('a');
    anchorElement.href = url;
    anchorElement.download = fileName ?? '';
    anchorElement.click();
    anchorElement.remove();
    URL.revokeObjectURL(url);
}

然后在Blazor组件中调用后端接口并触发下载：

@inject HttpClient Http
@inject IJSRuntime JSRuntime

<button @onclick="DownloadFile">下载文件</button>

@code {
    private async Task DownloadFile()
    {
        // 调用后端接口获取文件流
        var response = await Http.GetAsync("api/file/download?filePath=/files/test.pdf");
        if (response.IsSuccessStatusCode)
        {
            // 获取文件名和内容流
            var fileName = response.Content.Headers.ContentDisposition?.FileName?.Trim('"') ?? "test.pdf";
            var stream = await response.Content.ReadAsStreamAsync();
            // 调用JS函数触发下载
            await JSRuntime.InvokeVoidAsync("downloadFileFromStream", fileName, stream);
        }
    }
}

Blazor Server模式下载文件

Blazor Server模式下组件运行在服务端，可以直接通过返回文件流的方式实现下载，无需依赖复杂的JavaScript互操作。实现方式如下：

@inject NavigationManager Navigation

<button @onclick="DownloadFile">下载文件</button>

@code {
    private void DownloadFile()
    {
        // 拼接下载接口地址，直接跳转触发下载
        var downloadUrl = "api/file/download?filePath=/files/test.pdf";
        Navigation.NavigateTo(downloadUrl, true);
    }
}

如果需要更灵活的控制，也可以在组件中使用HttpClient调用接口后，通过服务端返回文件流再推送到客户端，不过直接跳转的方式实现更简单，适合大多数场景。

注意事项

• 文件大小限制：Blazor WebAssembly模式下如果文件过大，可能会导致内存占用过高，建议大文件下载采用分片或者直链跳转的方式。
• 跨域问题：如果前端和后端接口不在同一个域，需要配置CORS策略，允许前端域访问文件下载接口。
• 文件类型处理：如果是特殊类型的文件，比如图片、视频，可以修改后端接口的Content-Type，让浏览器正确识别文件类型。
• 路径安全：后端接口需要对传入的文件路径做校验，避免目录遍历漏洞，不要直接使用用户传入的路径读取服务器文件。

Blazor文件下载服务器客户端交互ASP.NET_CoreWeb开发修改时间：2026-06-14 16:45:29