如何通过Node.js实现从本地MinIO桶下载文件至用户机器？

问题1：将文件直接传输到用户浏览器 #

核心逻辑 #

不要把MinIO文件下载到后端本地磁盘，而是把MinIO返回的文件流直接转发给浏览器的HTTP响应。利用Node.js的stream.pipe()实现无本地存储的流式传输，同时设置正确的响应头触发浏览器下载行为。

代码示例 #

const express = require('express');
const Minio = require('minio');
const app = express();

// 初始化MinIO客户端
const minioClient = new Minio.Client({
  endPoint: '你的MinIO服务器IP',
  port: 9000,
  useSSL: false,
  accessKey: '你的AccessKey',
  secretKey: '你的SecretKey'
});

// 下载接口：先验证权限，再转发流
app.get('/download/:bucket/:filename', async (req, res) => {
  try {
    // 替换为实际的用户权限验证逻辑（如JWT校验、会话验证）
    const isAuthorized = true;
    if (!isAuthorized) {
      return res.status(403).send('无下载权限');
    }

    const { bucket, filename } = req.params;
    // 获取文件元信息，用于设置响应头
    const stat = await minioClient.statObject(bucket, filename);

    // 设置浏览器下载相关响应头
    res.setHeader('Content-Disposition', `attachment; filename="${encodeURIComponent(filename)}"`);
    res.setHeader('Content-Type', stat.metaData['content-type'] || 'application/octet-stream');
    res.setHeader('Content-Length', stat.size);

    // 从MinIO取流，直接pipe到响应对象
    const fileStream = await minioClient.getObject(bucket, filename);
    fileStream.pipe(res);

    // 处理流传输错误
    fileStream.on('error', (err) => {
      console.error('MinIO流异常:', err);
      res.status(500).send('文件下载失败');
    });

  } catch (err) {
    console.error('下载接口异常:', err);
    res.status(err.code === 'NotFound' ? 404 : 500)
       .send(err.code === 'NotFound' ? '文件不存在' : '服务器内部错误');
  }
});

app.listen(3000, () => {
  console.log('后端服务运行在 http://localhost:3000');
});

问题2：大文件分块下载（支持HTTP Range请求） #

核心逻辑 #

利用HTTP协议的Range请求头，浏览器会自动对大文件发起分块请求（例如Range: bytes=0-1024）。后端解析该请求头后，向MinIO请求对应字节范围的数据流，返回206 Partial Content响应，全程流式处理，避免后端内存溢出。

代码示例 #

app.get('/download-large/:bucket/:filename', async (req, res) => {
  try {
    // 用户权限验证（同上）
    const isAuthorized = true;
    if (!isAuthorized) {
      return res.status(403).send('无下载权限');
    }

    const { bucket, filename } = req.params;
    const stat = await minioClient.statObject(bucket, filename);
    const fileSize = stat.size;

    // 解析Range请求头
    const range = req.headers.range;
    if (!range) {
      // 无Range头时返回完整文件（降级处理）
      res.setHeader('Content-Disposition', `attachment; filename="${encodeURIComponent(filename)}"`);
      res.setHeader('Content-Type', stat.metaData['content-type'] || 'application/octet-stream');
      res.setHeader('Content-Length', fileSize);
      const fileStream = await minioClient.getObject(bucket, filename);
      fileStream.pipe(res);
      return;
    }

    // 解析字节范围：将"bytes=0-1023"转为start=0, end=1023
    const parts = range.replace(/bytes=/, "").split("-");
    const start = parseInt(parts[0], 10);
    const end = parts[1] ? parseInt(parts[1], 10) : fileSize - 1;
    const chunkSize = (end - start) + 1;

    // 向MinIO请求指定范围的数据流
    const fileStream = await minioClient.getObject(bucket, filename, { start, end });

    // 设置分块响应头
    res.status(206);
    res.setHeader('Content-Disposition', `attachment; filename="${encodeURIComponent(filename)}"`);
    res.setHeader('Content-Type', stat.metaData['content-type'] || 'application/octet-stream');
    res.setHeader('Content-Length', chunkSize);
    res.setHeader('Content-Range', `bytes ${start}-${end}/${fileSize}`);
    res.setHeader('Accept-Ranges', 'bytes');

    // 转发分块流到浏览器
    fileStream.pipe(res);

    fileStream.on('error', (err) => {
      console.error('MinIO分块流异常:', err);
      res.status(500).send('分块下载失败');
    });

  } catch (err) {
    console.error('大文件下载接口异常:', err);
    res.status(err.code === 'NotFound' ? 404 : 500)
       .send(err.code === 'NotFound' ? '文件不存在' : '服务器内部错误');
  }
});

关键说明 #

• 浏览器会自动完成分块数据的拼接，用户体验与普通下载一致
• 后端全程流式处理，不会将整个大文件加载到内存，避免内存溢出
• MinIO原生支持按字节范围读取数据，无需后端额外处理分块逻辑

内容的提问来源于stack exchange，提问作者True Vision _ Zunna Berry