Node.js+API生成PDF时图片不显示求助（Mustache&html-pdf-node）

可能的原因及对应解决方案 #

1. 图片路径问题 #

• 绝对/相对路径混乱：html-pdf-node运行时的工作目录可能和你预期不一致，优先用绝对路径。可以通过Node.js的__dirname拼接：

  const path = require('path');
  // 拼接本地图片绝对路径
  const imageAbsolutePath = path.join(__dirname, 'assets/images/your-image.png');
  // 传入Mustache模板时加上file://协议前缀
  const templateData = { imgUrl: `file://${imageAbsolutePath}` };
  

• 网络图片加载超时：如果用网络图片，要确保服务端能访问该地址，同时给html-pdf-node加等待参数确保图片加载完成：

  const options = {
    format: 'A4',
    waitForTimeout: 2000 // 等待2秒让图片加载
  };
  

2. Mustache模板引用格式错误 #

• 检查模板里的<img>标签src是否正确渲染：

  <!-- Mustache模板示例 -->
  <img src="{{imgUrl}}" alt="示例图片" />
  

  渲染后要确认生成的HTML中src是有效路径（绝对路径或可访问的网络地址）。

3. html-pdf-node配置缺失 #

• 开启本地文件访问权限：puppeteer（html-pdf-node依赖）默认可能限制本地文件访问，需在配置中添加参数：

  const options = {
    format: 'A4',
    args: ['--allow-file-access-from-files']
  };
  

• 系统依赖缺失：Linux环境下可能缺少libxss1、libnss3等依赖，导致puppeteer无法渲染图片，需安装对应系统依赖包。

4. Postman请求参数问题 #

• 确认POST请求传递的图片路径参数完整，没有被转义或截断。如果是本地路径，要确保服务端能读取到对应文件；如果是网络URL，要验证地址可直接访问。

快速排查步骤 #

1. 打印Mustache渲染后的完整HTML代码，检查<img>的src值是否正确。
2. 把渲染后的HTML直接在浏览器中打开，确认图片能正常显示，排除路径本身的问题。
3. 先用绝对路径引用本地图片测试生成PDF，逐步缩小问题范围。

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