在使用 node.js 模块 html-pdf 将 html 内容转换为 pdf 文档时，一个常见的问题是 html 中引用的本地图片无法正确显示。开发者可能会尝试使用绝对路径（如 file:///path/to/image.png）或网站根目录的相对路径（如 <img src="/templates/header-footer.png" />），但往往发现图片仍然无法加载。这背后的原因在于 html-pdf 内部使用的渲染引擎（如 phantomjs 或 chromium）需要一个明确的基准上下文来解析本地文件路径。如果没有正确配置，渲染引擎将无法定位到这些本地资源。
html-pdf 默认情况下对本地文件访问有一定的限制，并且其内部渲染引擎解析相对路径时，需要一个明确的“当前工作目录”或“基准 URL”。简单地在 HTML 中使用相对路径，如 src="templates/header-logo.png"，如果没有为其提供一个解析的起点，引擎就不知道 templates 目录相对于哪个位置。同样，直接使用操作系统的绝对路径，如果没有通过 file:/// 协议正确封装，或者 html-pdf 没有被授权访问本地文件，也会导致加载失败。
解决 html-pdf 中图片路径问题的关键在于在生成 PDF 的 options 对象中正确配置 base 属性，并启用 localUrlAccess。
以下是如何在 Node.js 代码中配置 html-pdf 以正确加载本地图片的示例：
const path = require('path');
const pdf = require('html-pdf');
// 假设你的 Node.js 模块的入口文件在 `dist` 目录下，
// 并且图片资源位于 `dist/templates` 目录下。
// `__dirname` 在这里将指向 `dist` 目录。
const currentModuleDir = __dirname;
// 构建 base 路径。它应该指向你的图片等静态资源所在的目录的“父目录”。
// 例如，如果图片在 `dist/templates/header-logo.png`，
// 那么 `base` 应该指向 `dist` 目录。
const basePathForHtmlPdf = path.join(currentModuleDir);
var options = {
format: "A4",
// 关键配置：定义 base 路径，使用 file:/// 协议。
// 确保 basePathForHtmlPdf 变量正确指向你的静态资源的基础目录。
base: "file:///" + basePathForHtmlPdf + "/",
// 允许访问本地文件系统。
localUrlAccess: true,
};
// 构造 HTML 内容
const htmlContent = `
<!DOCTYPE html>
<html>
<head>
<title>PDF Report</title>
<style>
body { font-family: Arial, sans-serif; }
img { max-width: 100px; height: auto; }
</style>
</head>
<body>
<h1>报告标题</h1>
<p>这是一份使用 html-pdf 生成的示例报告。</p>
<!--
引用图片时使用相对于 options.base 所指向的目录的相对路径。
如果 base 是 "file:///path/to/dist/"，
那么 src="templates/header-logo.png" 将解析为
"file:///path/to/dist/templates/header-logo.png"。
-->
<img src="templates/header-logo.png" alt="Header Logo" />
<p>报告内容详情...</p>
</body>
</html>
`;
// 生成 PDF
pdf.create(htmlContent, options).toFile('./report.pdf', function(err, res) {
if (err) {
console.error("生成 PDF 失败:", err);
return;
}
console.log("PDF 生成成功:", res.filename);
});HTML 内容示例：
立即学习“前端免费学习笔记（深入）”；
在 HTML 内部，图片引用应使用相对于 options.base 所定义路径的相对路径。
<!-- 如果 options.base 设置为 `file:///path/to/dist/` --> <!-- 那么 src="templates/header-logo.png" 将正确解析为 `file:///path/to/dist/templates/header-logo.png` --> <img src="templates/header-logo.png" alt="Header Logo" />
正确配置 html-pdf 的 base 选项和启用 localUrlAccess 是解决在生成的 PDF 中图片无法加载问题的关键。通过明确指定一个本地文件系统作为所有相对路径的基准，并授权渲染引擎访问本地文件，可以确保 HTML 中引用的图片、样式表等本地资源能够被 html-pdf 正确地识别和渲染，从而生成完整的、视觉效果正确的 PDF 文档。
以上就是解决 html-pdf 中图片路径不显示问题：正确配置 base 选项的详细内容，更多请关注php中文网其它相关文章！
全网最新最细最实用WPS零基础入门到精通全套教程！带你真正掌握WPS办公！ 内含Excel基础操作、函数设计、数据透视表等
Copyright 2014-2025 https://www.php.cn/ All Rights Reserved | php.cn | 湘ICP备2023035733号
947
收藏
