如何将含中文Unicode的HTML通过wkhtmltox正确渲染为PNG？

我之前也踩过wkhtmltox渲染和浏览器显示差异的坑，结合你已经安装好字体的情况，给你几个具体的排查和解决方向：

• 确保本地资源路径正确
  wkhtmltox的工作目录可能和你的Node.js脚本所在目录不一致，导致HTML里的相对路径资源（CSS、图片、字体）加载失败。你可以在转换参数里指定工作目录为脚本所在路径，或者把HTML里的资源都改成绝对路径：

  const wkhtmltox = require('wkhtmltox');
  const converter = new wkhtmltox();
  
  converter.image('./tagslegend.html', {
    'working-directory': __dirname, // 绑定工作目录到脚本所在文件夹
    format: 'png'
  }, (err, stream) => {
    if (err) throw err;
    // 处理输出流，比如写入文件
    stream.pipe(require('fs').createWriteStream('./output.png'));
  });
  

• 强制指定字体并确保加载
  即使系统装了字体，wkhtmltox可能没正确识别，建议在HTML的CSS里明确指定字体，甚至直接嵌入字体避免路径问题：

  @font-face {
    font-family: "YourTargetFont";
    /* 可以用系统字体路径，或者base64嵌入 */
    src: url('/usr/share/fonts/truetype/your-font.ttf') format('truetype');
  }
  
  body, * {
    font-family: "YourTargetFont", sans-serif !important;
  }
  

  另外可以添加--enable-local-file-access参数，允许wkhtmltox读取本地字体文件。

• 模拟浏览器环境，兼容现代特性
  wkhtmltox基于较老的WebKit内核，对一些现代CSS/JS特性支持有限：

  • 如果页面有JS动态渲染内容，一定要加javascript-delay参数给足够时间让JS执行完成，比如'javascript-delay': 1500（延迟1.5秒）
  • 开启CSS3支持：添加'enable-css3': true参数
  • 避免使用WebKit不支持的CSS属性，比如某些Grid布局的新特性，换成兼容写法

• 调试渲染过程
  用以下参数辅助排查问题：

  • --debug-javascript: 输出JS执行报错，看是否有脚本错误导致渲染异常
  • --dump-dom: 输出渲染后的DOM结构，和浏览器里的DOM对比，找出差异点
  • 先尝试生成PDF，wkhtmltox的PDF和PNG渲染逻辑一致，PDF更容易查看排版问题

• 确认服务器字体安装有效性
  在服务器上执行fc-list（Linux）或fc-list | grep "你的字体名"，确认字体确实被系统识别。如果是自定义字体，确保运行wkhtmltox的用户（比如Node进程的用户）有权限访问字体文件。

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