从JSON生成PDF时<img>标签图片无法显示的解决方法咨询

解决XSL中标签图片无法在PDF中显示的问题 #

我之前处理过类似的场景，核心问题其实是图片路径的解析逻辑不匹配——你的图片存在src/main/resources目录，但这个目录在编译、部署后的实际访问路径，和开发时的路径完全不同，而且HTML转PDF的工具需要精准定位到图片文件才能渲染出来。下面给你几个从简单到灵活的解决方案：

1. 先用绝对路径快速验证（排查问题） #

如果是本地开发阶段，可以先拿编译后图片的绝对路径测试，确认是不是路径问题。Maven/Gradle项目里，src/main/resources下的文件编译后会被放到target/classes（Maven）或build/resources/main（Gradle）目录。

比如你的图片是src/main/resources/logo.png，编译后的绝对路径可能是/Users/xxx/project/target/classes/logo.png，那在XSL里这么写：

<img src="file:///Users/xxx/project/target/classes/logo.png" alt="Logo" />

注意：Windows系统下路径要写成file:///C:/xxx/project/target/classes/logo.png，三个斜杠不能少。如果这样能显示，就确定是路径配置的问题，接下来可以用更通用的方式。

2. 动态传入ClassPath根路径（推荐，适合Java Web应用） #

硬编码绝对路径肯定不适合部署，最佳实践是在Java代码里动态获取ClassPath的根路径，作为参数传给XSLT转换器，再在XSL里拼接图片路径。

步骤1：Java代码传递参数 #

在你执行XSL转换的代码里，添加参数传递逻辑：

TransformerFactory factory = TransformerFactory.newInstance();
Transformer transformer = factory.newTransformer(new StreamSource(xslFile));

// 获取ClassPath根路径的绝对路径
String classPathRoot = getClass().getResource("/").getPath();
// 把路径传给XSL
transformer.setParameter("classPathRoot", classPathRoot);

// 执行XML转HTML的转换
transformer.transform(new StreamSource(xmlFile), new StreamResult(htmlFile));

步骤2：XSL接收并使用参数 #

在XSL文件开头定义参数，然后在<img>标签里引用：

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <!-- 定义要接收的路径参数 -->
    <xsl:param name="classPathRoot"/>
    
    <!-- 其他XSL逻辑 -->
    
    <img src="{$classPathRoot}logo.png" alt="Logo" />
</xsl:stylesheet>

不管是本地开发还是部署到服务器，代码都会自动获取正确的ClassPath路径，图片就能被PDF工具找到。

3. 迁移到Web静态资源目录（适合对外的Web应用） #

如果你的Web应用需要通过HTTP访问图片，也可以把图片移到src/main/webapp/images这类静态资源目录，然后用Web上下文路径引用：

步骤1：调整图片位置 #

把图片从src/main/resources移到src/main/webapp/images/logo.png。

步骤2：XSL里使用Web路径 #

如果PDF工具支持HTTP访问，直接写：

<img src="/your-app-context-path/images/logo.png" alt="Logo" />

或者在Java代码里获取Web应用根路径传给XSL：

// 在Servlet环境中获取WebApp根路径
String webAppRoot = servletContext.getRealPath("/");
transformer.setParameter("webAppRoot", webAppRoot);

然后XSL里写：

<img src="{$webAppRoot}images/logo.png" alt="Logo" />

4. 配置PDF工具的资源加载器（特殊场景） #

如果用的是Flying Saucer（XHTMLRenderer）或iText这类工具，可能需要自定义资源加载逻辑来识别ClassPath路径。比如用Flying Saucer时，可以设置UserAgentCallback：

ITextRenderer renderer = new ITextRenderer();
renderer.getSharedContext().setUserAgentCallback(new UserAgentCallback() {
    @Override
    public InputStream resolveAndOpenStream(String uri) {
        // 处理classpath开头的路径
        if (uri.startsWith("classpath:/")) {
            String resourcePath = uri.substring(10);
            return getClass().getResourceAsStream("/" + resourcePath);
        }
        // 其他情况用默认逻辑
        return super.resolveAndOpenStream(uri);
    }
});
// 加载HTML生成PDF
renderer.setDocument(new File(htmlPath));
renderer.layout();
renderer.createPDF(outputStream);

这时XSL里可以直接写：

<img src="classpath:/logo.png" alt="Logo" />

常见坑提醒 #

• 确保图片格式是PDF支持的（PNG、JPG、GIF都可以，WebP这类小众格式不行）；
• XSL生成的HTML要符合XHTML规范，<img>标签要闭合（用<img/>而不是<img>）；
• 路径里如果有空格，要转义成%20，或者用URI格式的路径。

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