Laravel+React.js项目PDF下载后无法加载打开报错问题

故障现象 #

已上传支持用户下载、阅读的PDF文件，可正常触发下载流程，但下载完成后文件无法正常打开，弹出错误提示：

Failed to load PDF

故障根因 #

• 路径分隔符不兼容：Laravel接口返回的download_link使用Windows系统的反斜杠\作为路径分隔符，Web环境标准路径分隔符为正斜杠/，反斜杠会被浏览器识别为转义字符，导致实际请求的文件地址错误，最终下载到的是404/403错误页的HTML内容而非真实PDF文件，这是该故障最常见的诱因。
• 静态资源映射缺失：如果PDF文件存储在Laravel的storage目录下，未执行php artisan storage:link命令生成public目录到storage目录的软链，直接访问路径无法拿到真实文件。
• 下载文件名配置错误：前端a标签的download属性未指定正确文件名，浏览器自动截取路径片段作为文件名，可能出现无后缀、后缀错误的问题，导致系统无法识别为PDF文件。

快速验证方法：将下载后无法打开的文件拖入记事本打开，如果内容是HTML代码（报错页、框架异常页内容），即可确认下载到的不是真实PDF文件，为路径/权限问题导致。

修复方案 #

Laravel后端修复 #

1. 统一路径格式，返回可直接访问的Web路径，禁止直接返回服务器本地的反斜杠路径。如果走公开静态资源访问，确保已执行软链命令，返回路径示例：

"pdf_link": [
    [
        // 用asset助手函数生成可直接访问的web地址，自动适配路径分隔符
        "download_link" => asset("storage/publications/May2022/yFj0H0aOQDBKzcAndio4.pdf"),
        "original_name" => "2021-Egitim-Degerlendirme-Raporu.pdf"
    ]
]

2. 若需要做权限校验不开放公开访问，可编写专门的下载接口，在接口中返回正确的文件响应与响应头，示例代码：

public function downloadPublicationPdf()
{
    // 实际场景可根据传入参数查询对应文件路径
    $fileRealPath = storage_path("app/public/publications/May2022/yFj0H0aOQDBKzcAndio4.pdf");
    $originalFileName = "2021-Egitim-Degerlendirme-Raporu.pdf";

    return response()->download($fileRealPath, $originalFileName, [
        "Content-Type" => "application/pdf"
    ]);
}

React前端修复 #

修正a标签的download属性值，传入接口返回的原始文件名，确保下载的文件后缀正确：

<a
  className="edu-btn"
  href={data?.pdf_link[0].download_link}
  download={data?.pdf_link[0].original_name}
>
  Download
  <i className="icon-arrow-right-line-right"></i>
</a>

修复完成后先直接在浏览器访问接口返回的download_link地址，确认可以正常预览PDF内容，再测试下载功能即可。

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