TuesPechkin/Wkhtmltopdf转换PDF时Base64编码图片无法加载问题

解决方案 #

• Base64格式校验
  wkhtmltopdf对Base64资源的格式兼容性远低于普通浏览器，请优先检查两项内容：
  1. 确保所有img标签的src属性的data URI前缀和图片实际MIME类型完全匹配，比如JPG对应data:image/jpeg;base64,、PNG对应data:image/png;base64,，避免MIME类型错配
  2. 清理Base64字符串中的换行、空格、制表符等多余字符，MailKit解析出的内联图片Base64默认可能带分段换行，需提前做字符清理后再替换CID
• 替换wkhtmltopdf版本
  TuesPechkin内置的Win64EmbeddedDeployment打包的wkhtmltopdf版本较老，对Base64资源、WebP等新型图片格式支持存在缺陷。可以手动下载最新版wkhtmltopdf二进制文件，初始化IConverter时替换内置部署逻辑，改为指向本地的wkhtmltopdf文件路径即可。
• 补全配置参数
  除已开启的LoadImages、PrintBackground参数外，需在ObjectSettings中额外添加以下配置：

  PrintMediaType = true,
  EnableLocalFileAccess = true,
  LoadSettings = new LoadSettings { ErrorHandling = "ignore" }
  

  上述配置可以提高wkhtmltopdf对内联资源的解析权限，避免单张资源加载失败影响整体转换结果。
• 替换资源加载方式
  如果Base64加载始终异常，可以调整HTML修改逻辑：不要将内联图片转Base64，而是将邮件内联图片导出到本地临时目录，把img标签的src替换为对应图片的本地绝对路径，wkhtmltopdf对本地文件路径的加载稳定性远高于Base64资源。
• 底层逻辑排查
  将修改后的HTML字符串写入本地临时HTML文件，直接用wkhtmltopdf命令行工具转换该文件：如果命令行转换结果也存在图片占位框，问题出在HTML资源本身或wkhtmltopdf版本；如果命令行转换正常，说明是TuesPechkin封装层的参数传递bug，可直接更换为调用wkhtmltopdf进程的方案绕过封装层问题。

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