Node.js使用ytdl-core返回YouTube视频流 客户端无法下载问题

两种错误写法的本质问题如下：

• 直接执行video.pipe(response)时未设置正确的Content-Type、Content-Disposition响应头，自定义客户端无法识别返回内容的文件类型，会默认将二进制流按文本编码解析，最终呈现为乱码。
• 直接执行response.status(200).send(video)时，Web框架会将传入的可读流对象当做普通JavaScript对象序列化为JSON返回，根本没有读取流内存储的视频二进制数据，客户端拿到的自然是流对象的内部属性结构。

核心逻辑是先设置符合文件下载规范的响应头，再将ytdl-core生成的视频流传入响应对象，同时做好错误捕获避免服务异常。以下是Express框架的实现示例，原生HTTP模块逻辑完全一致，仅API写法稍有区别：

const ytdl = require('ytdl-core');
const express = require('express');
const app = express();

app.get('/api/video/download', async (req, res) => {
  const videoId = req.query.vid;
  // 提前校验视频ID合法性
  if (!ytdl.validateID(videoId)) {
    return res.status(400).send('无效的YouTube视频ID');
  }

  try {
    // 获取视频元信息
    const videoInfo = await ytdl.getInfo(videoId);
    // 选择包含音视频的最高画质MP4格式，可根据业务需求调整画质筛选规则
    const targetFormat = ytdl.chooseFormat(videoInfo.formats, {
      quality: 'highest',
      filter: 'audioandvideo'
    });
    // 编码文件名，避免特殊字符、中文导致响应头解析失败
    const fileName = encodeURIComponent(`${videoInfo.videoDetails.title}.${targetFormat.container}`);

    // 设置下载必需的响应头
    res.setHeader('Content-Type', targetFormat.mimeType.split(';')[0]);
    res.setHeader('Content-Disposition', `attachment; filename="${fileName}"; filename*=UTF-8''${fileName}`);
    // 可选：添加断点续传支持
    res.setHeader('Accept-Ranges', 'bytes');

    // 生成视频流并接入响应
    const videoStream = ytdl(videoId, { format: targetFormat });
    // 监听流错误，防止未捕获异常导致服务崩溃
    videoStream.on('error', (err) => {
      console.error('视频流传输异常:', err);
      if (!res.headersSent) {
        res.status(500).send('视频传输失败');
      }
    });
    videoStream.pipe(res);
  } catch (err) {
    console.error('视频下载接口异常:', err);
    if (!res.headersSent) {
      res.status(500).send('视频信息获取失败');
    }
  }
});

app.listen(3000, () => console.log('服务启动在3000端口'));

无论使用什么语言、什么请求库开发自定义客户端，核心要遵守两个规则：

1. 禁止将响应当普通文本/JSON解析，必须按二进制类型接收响应内容
2. 接收到完整二进制内容后，按响应头标注的视频格式写入本地文件即可

以下是两种常见客户端的实现示例：

浏览器端（fetch实现） #

async function getVideo(videoId) {
  const response = await fetch(`/api/video/download?vid=${videoId}`);
  // 从响应头解析文件名
  const disposition = response.headers.get('Content-Disposition');
  const fileName = decodeURIComponent(disposition.match(/filename\*=UTF-8''([^;]+)/)[1]);
  // 将响应接收为二进制Blob对象
  const videoBlob = await response.blob();
  // 生成临时链接触发本地下载
  const tempUrl = window.URL.createObjectURL(videoBlob);
  const trigger = document.createElement('a');
  trigger.href = tempUrl;
  trigger.download = fileName;
  trigger.click();
  window.URL.revokeObjectURL(tempUrl);
}

Node.js端（node-fetch实现，支持大文件低内存占用） #

const fetch = require('node-fetch');
const fs = require('fs');
const { pipeline } = require('stream/promises');

async function saveVideoToLocal(videoId, localSavePath) {
  const response = await fetch(`http://127.0.0.1:3000/api/video/download?vid=${videoId}`);
  // 直接将响应流管道连接到本地文件写入流，无需全量加载视频到内存
  await pipeline(response.body, fs.createWriteStream(localSavePath));
}

• 不要在pipe调用前执行res.send()、res.json()等会提前结束响应的方法，否则会导致流传输中断，文件损坏。
• 如果使用axios作为请求客户端，必须显式配置responseType参数：浏览器端设为'blob'，Node.js端设为'stream'，默认配置会将二进制响应按UTF-8文本解析，必然出现乱码。
• 如果服务端前部署了Nginx等反向代理，需要关闭代理的响应缓冲配置，否则大视频会等待代理全量缓存后才开始传输，容易触发超时问题。
• 文件名必须做URI编码，否则中文、特殊符号会导致客户端识别文件名乱码。

内容的提问来源于stack exchange，提问作者Leo