pdfkit生成PDF时未嵌入图片问题排查求助

我来帮你捋捋这个问题——用pdfkit（本质是调用wkhtmltopdf）生成PDF时图片不显示，大概率是这几个常见坑，你一个个排查试试：

• 图片路径是重灾区
  HTML里的相对路径在浏览器里能正常解析，但pdfkit运行时的工作目录可能和HTML文件所在目录不一样，导致wkhtmltopdf找不到图片。给你两个解决思路：

  1. 把HTML里的图片src改成绝对路径，比如/Users/xxx/project/images/trend.png（Windows就是C:\xxx\project\images\trend.png）；
  2. 在pdfkit的options里开启本地文件访问权限，同时确保相对路径是相对于脚本运行目录的：

     import os
     options = {
         'page-size': 'A4',
         'dpi': 400,
         'enable-local-file-access': None  # 关键参数：允许加载本地文件
     }
     # 也可以先把HTML文件的路径转成绝对路径，避免路径歧义
     htmlFilePath = os.path.abspath(htmlFilePath)
     pdfkit.from_file(htmlFilePath, pdfFilePath, options=options, css=css)
     

  另外别忘了检查img标签的src有没有拼写错误，比如少打了文件夹名、后缀名写错之类的低级错误。

• wkhtmltopdf的默认限制
  很多新版本的wkhtmltopdf默认禁用了本地文件访问，所以必须显式加上enable-local-file-access参数，不然就算路径对了也加载不了图片。

• CSS样式搞鬼
  你引入的两个CSS文件里，有没有对img标签设置了display: none、visibility: hidden或者其他隐藏类？可以先临时去掉css参数，生成一次PDF看看图片能不能显示——如果能，就去CSS里排查对应的样式规则。

• 图片格式/编码问题
  浏览器能显示的图片格式（比如WebP），wkhtmltopdf可能支持不好，试试把图片转换成PNG或JPG格式再测试。另外如果HTML文件编码不是UTF-8，也可能导致路径解析乱码，记得在HTML的head里加上<meta charset="UTF-8">。

• 极简测试法
  要是上面的方法都没用，写个极简的HTML文件（比如只包含<img src="绝对路径的图片">），用pdfkit直接生成PDF，看能不能显示。如果能，就说明是原HTML里的其他元素（比如复杂布局、JS）影响了图片加载；如果还是不能，那可能是wkhtmltopdf的版本问题，试试换个稳定版本的wkhtmltopdf。

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