Node.js代理流式传输Clio API文件到JS客户端后文件变大损坏如何解决

根因说明 #

Node.js服务端框架默认会将响应体按UTF-8编码处理，二进制音视频文件里的不可见字符会被强制转换为UTF-8替换字符（即你看到的�符号），每个单字节的不可见字符会被转成3字节的替换符，最终就会出现文件体积翻倍、结构损坏无法播放的问题。
你将流写入本地文件时正常，是因为fs.createWriteStream默认按二进制流写入，不会做编码转换。

修复方案 #

1. 当前request包版本修复 #

在pipe到客户端响应前，明确关闭编码自动转换，透传正确的响应头：

// 设置二进制响应头
res.setHeader('Content-Type', 'application/octet-stream');
res.setHeader('Content-Disposition', `attachment; filename="download.mp4"`);
// 禁用响应的自动UTF-8编码
res.setEncoding(null);

request({
  url: `https://app.clio.com/api/v4/documents/${documentId}/download.json`,
  headers: { Authorization: `Bearer ${accessToken}` },
  // 要求request返回原始二进制流，不做编码处理
  encoding: null
}).pipe(res);

2. Axios版本实现（适配你常用的技术栈） #

如果要替换为axios实现流式代理，参考如下代码：

const axios = require('axios');

// 提前设置响应头
res.setHeader('Content-Type', 'application/octet-stream');
res.setHeader('Content-Disposition', `attachment; filename="download.mp4"`);
res.setEncoding(null);

const clioRes = await axios({
  method: 'GET',
  url: `https://app.clio.com/api/v4/documents/${documentId}/download.json`,
  headers: { Authorization: `Bearer ${accessToken}` },
  // 关键配置：指定响应类型为流，避免axios自动转成文本/JSON
  responseType: 'stream'
});

// 可选：透传Clio返回的文件长度，方便客户端显示下载进度
res.setHeader('Content-Length', clioRes.headers['content-length']);

// 直接将Clio返回的流转发给客户端
clioRes.data.pipe(res);

客户端适配注意事项 #

调用代理接口时需要明确指定响应类型为blob，避免浏览器自动将响应当成文本处理：

// fetch示例
fetch('/你的代理接口地址')
  .then(res => res.blob())
  .then(blob => {
    // 下载逻辑
    const downloadUrl = URL.createObjectURL(blob);
    const aTag = document.createElement('a');
    aTag.href = downloadUrl;
    aTag.download = 'test.mp4';
    aTag.click();
    URL.revokeObjectURL(downloadUrl);
  });

// 客户端axios示例
axios.get('/你的代理接口地址', {
  responseType: 'blob'
}).then(res => {
  // 同上下载逻辑
})

内容的提问来源于stack exchange，提问作者Leslie Jones-Dove