依赖远程仓库时PDF内HTML书签/超链接失效问题

遇到这种本地依赖正常、切换到远程依赖就出问题的情况，大概率是构建或依赖打包环节的细节没处理到位，结合iText pdfHTML的特性，我给你梳理几个实用的排查方向：

• 检查远程依赖的打包完整性
  你可以把远程仓库里的文档生成依赖包下载下来解压，对比里面的HTML模板和本地仓库的版本是不是完全一致——重点看那些带id的书签元素、以及对应的href="#xxx"链接有没有被篡改或遗漏。有些构建工具（比如Maven的maven-assembly-plugin、Gradle的shadowJar）如果配置不当，会过滤掉HTML的某些属性，或者漏打包模板文件，这是最常见的原因。

• 验证iText pdfHTML版本一致性
  本地开发环境和远程依赖中iText相关组件的版本是不是完全匹配？不同版本的pdfHTML对HTML书签的解析逻辑可能有差异，比如旧版本处理锚点链接时存在bug，你本地用了修复后的版本，但远程依赖的库还停留在旧版，就会导致链接失效。

• 排查构建时的资源过滤/转义规则
  有些项目构建时会对HTML这类资源文件做变量替换或特殊字符转义，如果配置不当，可能会破坏书签链接。比如Maven的resources插件开启过滤后，误把#当成变量分隔符，把href="#section1"改成了无效内容。你可以检查远程依赖的构建配置，看看有没有这类可能修改HTML模板的规则。

• 检查资源加载逻辑的适配性
  本地依赖时，库可能是从文件系统直接读取HTML模板，但远程依赖是从JAR包中加载资源，如果加载逻辑没处理好（比如没用到ClassLoader.getResourceAsStream()这类正确的方式），iText可能无法正确解析模板里的锚点关系。可以看看文档生成库中加载HTML的代码，确认资源读取逻辑兼容JAR内资源的场景。

• 尝试最小化测试案例
  写一个极简的测试项目：只引入远程的文档生成依赖，用一个最基础的带书签的HTML模板生成PDF。如果这个最小案例也出问题，那基本可以确定是远程依赖本身的打包问题；如果没问题，那就是你主项目里的其他配置、代码和远程依赖产生了冲突。

内容来源于stack exchange