Stirling-PDF项目中SYSTEM_ROOTURIPATH环境变量在PDF合并功能中的失效问题分析

在Stirling-PDF项目0.44.2版本中，用户报告了一个关于环境变量SYSTEM_ROOTURIPATH在PDF合并功能中未正确生效的技术问题。这个问题导致前端请求的资源路径没有按照预期包含配置的基础URI路径前缀。

问题现象

当用户通过Docker部署Stirling-PDF服务并设置了SYSTEM_ROOTURIPATH环境变量为"/pdf-tools/"时，系统在PDF合并功能中生成的资源请求路径出现了偏差。具体表现为：

• 预期请求路径：http://x.x.x.x/pdf-tools/pdfjs-legacy/pdf.mjs
• 实际请求路径：http://x.x.x.x/pdfjs-legacy/pdf.mjs

这种路径错误导致了504网关超时错误，因为服务无法在未包含基础URI路径前缀的位置找到所需资源。

技术背景

SYSTEM_ROOTURIPATH是Stirling-PDF项目中用于配置应用基础路径的重要环境变量。在微服务架构和容器化部署场景下，这种配置特别重要，它允许：

1. 同一主机上部署多个服务时避免路径冲突
2. 通过反向代理实现路径路由
3. 支持自定义部署路径的需求

问题根源

通过分析可以确定，问题出在前端JavaScript代码中生成资源请求路径时，没有正确考虑SYSTEM_ROOTURIPATH配置。具体来说：

1. 后端服务正确接收并处理了环境变量配置
2. 前端静态资源路径生成逻辑存在硬编码或配置缺失
3. PDF合并功能特有的资源加载逻辑没有继承全局路径配置

解决方案

项目维护者在后续提交中修复了这个问题。修复方案可能包括：

1. 修改前端资源路径生成逻辑，确保包含配置的基础路径
2. 统一前后端的路径处理机制
3. 增加路径配置的全局访问点，避免硬编码

最佳实践建议

对于使用类似配置的开发者，建议：

1. 在开发过程中充分测试路径配置在各种功能模块中的一致性
2. 实现路径处理的统一工具函数，避免重复代码
3. 考虑使用前端框架的路由机制来处理基础路径
4. 在容器化部署时，验证环境变量的传递和解析

这个问题虽然看似简单，但它揭示了在Web应用开发中路径处理的重要性，特别是在需要支持灵活部署场景的项目中。正确的路径处理不仅能确保功能正常，还能提高应用的可移植性和部署灵活性。