React从Node.js服务器下载PDF文件失败的问题排查与解决

Postman能正常下载是因为它会自动解析响应的文件流并触发下载，但React前端用axios/fetch请求时，不会自动触发浏览器的下载行为，必须手动处理二进制响应并创建下载链接。下面是具体问题点和解决办法：

1. 前端请求未配置二进制响应类型 #

默认情况下，axios/fetch会把响应解析为JSON或文本，无法正确处理PDF的二进制数据流。必须显式设置响应类型为blob。

Axios 示例 #

import axios from 'axios';

const handleDownload = async () => {
  try {
    const response = await axios.post('/cv-download', 
      { /* 这里传接口需要的参数，比如文件ID */ },
      {
        responseType: 'blob', // 关键：指定响应类型为blob
        headers: {
          'Content-Type': 'application/json' // 根据接口要求设置请求头
        }
      }
    );
    
    // 处理下载逻辑
    const url = window.URL.createObjectURL(new Blob([response.data]));
    const link = document.createElement('a');
    link.href = url;
    // 从响应头获取文件名，或者手动指定
    const filename = response.headers['content-disposition']?.split('filename=')[1] || 'resume.pdf';
    link.setAttribute('download', filename);
    document.body.appendChild(link);
    link.click();
    // 清理资源
    document.body.removeChild(link);
    window.URL.revokeObjectURL(url);
  } catch (error) {
    console.error('下载失败:', error);
  }
};

Fetch 示例 #

const handleDownload = async () => {
  try {
    const response = await fetch('/cv-download', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ /* 接口所需参数 */ })
    });
    
    if (!response.ok) throw new Error('请求失败');
    
    const blob = await response.blob();
    const url = window.URL.createObjectURL(blob);
    const link = document.createElement('a');
    link.href = url;
    const filename = response.headers.get('Content-Disposition')?.split('filename=')[1] || 'resume.pdf';
    link.setAttribute('download', filename);
    document.body.appendChild(link);
    link.click();
    document.body.removeChild(link);
    window.URL.revokeObjectURL(url);
  } catch (error) {
    console.error('下载失败:', error);
  }
};

2. 服务器响应头配置是否正确 #

确保Node.js服务器返回的响应头包含正确的文件类型和下载标识，否则前端可能无法识别为可下载文件。

Express 控制器示例 #

const downloadFile = async (req, res) => {
  try {
    const { fileId } = req.body; // 假设通过参数获取文件路径
    const filePath = path.join(__dirname, 'uploads', `${fileId}.pdf`);
    
    // 检查文件是否存在
    if (!fs.existsSync(filePath)) {
      return res.status(404).json({ message: '文件不存在' });
    }
    
    // 设置响应头
    res.setHeader('Content-Type', 'application/pdf');
    res.setHeader('Content-Disposition', `attachment; filename="resume-${fileId}.pdf"`);
    // 如果有跨域需求，确保允许获取Content-Disposition头
    res.setHeader('Access-Control-Expose-Headers', 'Content-Disposition');
    
    // 流式传输文件
    const fileStream = fs.createReadStream(filePath);
    fileStream.pipe(res);
  } catch (error) {
    res.status(500).json({ message: '下载失败', error: error.message });
  }
};

注意：Access-Control-Expose-Headers必须设置，否则前端无法读取Content-Disposition头来获取文件名。

3. 跨域问题（如果存在） #

如果前端和服务器不在同一域名下，需要确保服务器配置了正确的CORS规则，允许POST请求，并且允许暴露必要的响应头（如Content-Disposition）。

Express CORS 配置示例 #

const cors = require('cors');

app.use(cors({
  origin: 'http://your-frontend-domain.com', // 或设置为true允许所有
  credentials: true,
  exposedHeaders: ['Content-Disposition'] // 暴露这个头给前端
}));

4. 常见排查点 #

• 检查前端请求的参数是否和Postman一致，确保服务器能正确找到文件
• 在浏览器控制台查看请求的响应，确认返回的是200 OK且响应类型为blob
• 检查服务器端的文件路径是否正确，权限是否足够读取文件

内容的提问来源于stack exchange，提问作者Javad-M