Azure App Service沙箱环境使用wkhtmltopdf生成PDF失败排查

• 开发需求：整合同一目录下的页眉（header）、页脚（footer）、正文（body）3份HTML文件生成PDF，项目部署在操作系统为Windows的标准版计划Azure App Service上。
• 异常表现：本地以API形式调试时PDF生成功能运行正常，部署到Azure App Service后功能失效，既无法生成目标PDF文件，也无法访问已存在的PDF文件。
• 测试方案：选择通过Kudu CLI直接执行PDF生成命令开展测试，相比硬编码代码、反复修改App Service配置变量的方式，命令行测试可以更快调整参数验证效果。目前暂不确定Azure App Service的文件系统权限配置规则，也无法确认异常原因是平台安全策略阻止exe文件执行，还是程序的文件创建操作被无报错静默拦截。

目录结构 #

当前wkhtmltopdf程序所在工作目录的文件结构如下：

D:\home\site\wwwroot\wkhtmltopdf>ls
bmkcontent.html
bmkcontent_files
bmkfooter.html
bmkfooter_files
bmkheader.html
bmkheader_files
ignore
wkhtmltopdf.exe

所有命名格式为xxxxx_files的文件夹中，存放对应HTML文件依赖的.css、.js资源，用于实现页面样式渲染、页码统计等基础功能。

测试执行的生成命令 #

D:\home\site\wwwroot\wkhtmltopdf\wkhtmltopdf.exe --enable-local-file-access  --header-html D:\home\site\wwwroot\wkhtmltopdf\bmkheader.html --header-spacing 10 D:\home\site\wwwroot\wkhtmltopdf\bmkcontent.html --footer-html D:\home\site\wwwroot\wkhtmltopdf\bmkfooter.html --footer-spacing 10 D:\home\site\wwwroot\wkhtmltopdf\test.pdf  --enable-local-file-access --load-error-handling ignore

运行报错信息 #

执行上述命令时，wkhtmltopdf返回如下警告：

Warning: Failed loading page D:\\home\site\wwwroot\wkhtmltopdf\test.pdf (ignored)

程序版本信息 #

部署在App Service上的wkhtmltopdf版本如下：

D:\home\site\wwwroot\wkhtmltopdf>wkhtmltopdf --version
wkhtmltopdf 0.12.6 (with patched qt)

本地验证结果 #

本地环境执行同逻辑命令可正常生成PDF，重复添加--enable-local-file-access参数不会触发异常，本地可正常运行的命令参考如下：

--enable-local-file-access --header-html .\wkhtmltopdf\bmkheader.html --header-spacing 10 .\wkhtmltopdf\bmkcontent.html --footer-html .\wkhtmltopdf\bmkfooter.html --footer-spacing 10 C:\Users\public\Documents\aaaa.pdf --> works like a charm

目前已多次调整目录路径、执行参数均未解决问题。

• 核心报错原因是命令参数顺序错误：wkhtmltopdf对参数顺序有强校验规则，全局配置项、页眉页脚配置必须放在所有输入HTML文件之前，输出PDF的路径必须放在整个命令的最末尾。当前在Azure执行的命令把输出路径test.pdf放在了--enable-local-file-access、--load-error-handling ignore两个全局参数之前，程序会把test.pdf识别为待加载的输入页面，才会返回“加载页面失败”的警告。本地可正常运行的命令本身就是把输出路径放在命令最后，和Azure上执行的命令参数顺序存在差异，这是本地正常、云端报错的核心差异点。
• 修正参数顺序后可直接执行的命令参考：

D:\home\site\wwwroot\wkhtmltopdf\wkhtmltopdf.exe --enable-local-file-access --load-error-handling ignore --header-html D:\home\site\wwwroot\wkhtmltopdf\bmkheader.html --header-spacing 10 --footer-html D:\home\site\wwwroot\wkhtmltopdf\bmkfooter.html --footer-spacing 10 D:\home\site\wwwroot\wkhtmltopdf\bmkcontent.html D:\home\site\wwwroot\wkhtmltopdf\test.pdf

• 平台限制说明：Windows标准版计划Azure App Service不会拦截放在D:\home\site\wwwroot路径下的自定义控制台exe执行，D:\home路径下的持久化存储默认开放完整读写权限，不存在静默拦截文件创建的安全策略，不需要额外调整平台权限配置。
• 调整参数后如果仍有异常，可按以下方向排查：
  • 所有HTML文件中引用的css、js资源不要使用相对路径，统一替换为D:\home\开头的全绝对路径，避免wkhtmltopdf运行时工作目录和Kudu CLI工作目录不一致导致资源加载失败。
  • 如果页眉页脚的页码统计JS功能失效，追加--javascript-delay 1000参数，给前端JS执行预留足够渲染时间——App Service沙箱内的GDI渲染速度比本地环境慢，容易出现JS未执行完就完成PDF渲染的问题。
  • 如果PDF生成成功但无法通过HTTP访问，先检查站点根目录的web.config是否配置了pdf后缀的请求拦截，同时补充pdf扩展名对应的MIME类型application/pdf，避免IIS默认拦截未知后缀的静态文件访问。

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