Symfony5.4集成knp_snappy生成PDF遇文件拦截与协议错误求助

使用Symfony 5.4、knp_snappy 1.9、wkhtmltopdf 12.6及Webpack-Encore 1.16时，仅部署环境出现PDF生成失败，开发环境（类生产ISO环境）无异常。近两周部署环境生成PDF时，本地静态文件（CSS、图片、JS等）被拦截访问，同时多次出现“Failed to load about:blank，Protocol 'about' is unknown”错误，退出码为1。

错误日志 #

snappy.ERROR: An error happened while generating "/tmp/knp_snappy641b08fd3d2325.77113643.pdf". {"command":"xvfb-run /usr/bin/wkhtmltopdf --lowquality '/tmp/knp_snappy641b08fd3d1788.78365795.html' '/tmp/knp_snappy641b08fd3d2325.77113643.pdf'","status":1,"stdout":"","stderr":"QStandardPaths: XDG_RUNTIME_DIR not set, defaulting to '/tmp/runtime-peir'\nLoading page (1/2)\n[>                                                           ] 0%\r[=====================>                                      ] 35%\rWarning: Blocked access to file /PEIR/www/app/public/build/1.329d65bc.css\nWarning: Blocked access to file /PEIR/www/app/public/build/app.b69d4246.css\nWarning: Blocked access to file /PEIR/www/app/public/build/images/urne.png\nWarning: Blocked access to file /PEIR/www/app/public/build/images/logos_metiers/marianne/marianne.png\nWarning: Blocked access to file /PEIR/www/app/public/js/popper.js\nWarning: Blocked access to file /PEIR/www/app/public/build/runtime.d94b3b43.js\nWarning: Blocked access to file /PEIR/www/app/public/build/0.8ecf1583.js\nWarning: Blocked access to file /PEIR/www/app/public/build/1.0807a62f.js\nWarning: Blocked access to file /PEIR/www/app/public/build/app.bffbb929.js\nError: Failed to load about:blank, with network status code 301 and http status code 0 - Protocol \"about\" is unknown\nError: Failed to load about:blank, with network status code 301 and http status code 0 - Protocol \"about\" is unknown\nError: Failed to load about:blank, with network status code 301 and http status code 0 - Protocol \"about\" is unknown\nError: Failed to load about:blank, with network status code 301 and http status code 0 - Protocol \"about\" is unknown\nError: Failed to load about:blank, with network status code 301 and http status code 0 - Protocol \"about\" is unknown\nError: Failed to load about:blank, with network status code 301 and http status code 0 - Protocol \"about\" is unknown\nError: Failed to load about:blank, with network status code 301 and http status code 0 - Protocol \"about\" is unknown\nError: Failed to load about:blank, with network status code 301 and http status code 0 - Protocol \"about\" is unknown\nError: Failed to load about:blank, with network status code 301 and http status code 0 - Protocol \"about\" is unknown\nWarning: Blocked access to file \nError: Failed to load about:blank, with network status code 301 and http status code 0 - Protocol \"about\" is unknown\n[============================================================] 100%\rPrinting pages (2/2)                                               \n[>                                                           ] \rDone                                                           \nExit with code 1 due to network error: ProtocolUnknownError\n"} []

knp_snappy配置 #

knp_snappy:
    pdf:
        enabled: true
        binary: '%env(WKHTMLTOPDF_PATH)%'
        options:
            enable-local-file-access: true
    image:
        enabled: true
        binary: '%env(WKHTMLTOIMAGE_PATH)%'
        options:
            enable-local-file-access: true

解决思路 #

• 验证enable-local-file-access参数生效：直接在部署环境命令行手动执行wkhtmltopdf命令，显式添加--enable-local-file-access参数测试，确认是否解除静态文件拦截。
• 排查about:blank跳转逻辑：检查PDF模板及关联JS代码，是否存在主动跳转到about:blank的逻辑；可尝试添加--disable-javascript参数禁用JS加载，验证是否消除该错误。
• 检查文件权限：确认wkhtmltopdf运行用户（如www-data）对/PEIR/www/app/public/目录及下属静态文件有读取权限，必要时调整目录或文件权限。
• 修复环境变量缺失：在执行xvfb-run命令前手动设置XDG_RUNTIME_DIR环境变量，如export XDG_RUNTIME_DIR=/tmp/runtime-peir，再运行PDF生成命令。
• 排查版本兼容性：wkhtmltopdf 0.12.6存在部分协议处理已知bug，可尝试升级至最新稳定版或回退到之前验证可用的版本，确认是否为版本引入的问题。

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