PEX可执行文件中Jinja2无法找到HTML模板问题求助

问题根源分析 #

1. -R参数与包资源配置冲突
   你使用-R utils/tasks/templates会将模板目录直接复制到PEX根目录，但同时setup相关配置（MANIFEST.in/setup.cfg/setup.py）又把模板作为包资源打包到了.deps目录的包文件中。这种重复放置会导致Jinja2的加载器无法匹配到正确的模板路径。

2. PEX运行时路径的特殊性
   PEX运行时会在临时目录解压执行，本地开发时的文件路径和PEX运行时的实际路径并不一致。如果Jinja2加载器配置的是本地开发时的路径，或者依赖文件系统路径而非包资源路径，就会出现找不到模板的情况。

解决方法 #

方法一：依赖Python包资源机制（推荐） #

完全移除-R参数，依靠Python的包资源规范来管理模板：

• 确认setup配置正确包含模板：
  • MANIFEST.in添加：

    recursive-include utils/tasks/templates *.html
    

  • setup.py中配置package_data：

    setup(
        # 其他配置项...
        package_data={
            'utils.tasks': ['templates/*.html']
        },
        include_package_data=True
    )
    

• 调整Jinja2加载器为PackageLoader，从包内加载模板：

  from jinja2 import PackageLoader, Environment
  
  env = Environment(loader=PackageLoader('utils.tasks', 'templates'))
  

• 重新打包PEX：

  pex --disable-cache . -e ${PYTHON_ENTRYPOINT} -o app.pex
  

方法二：适配-R参数的路径加载 #

如果必须用-R参数复制模板到PEX根目录，需要在代码中动态获取PEX运行时的实际根路径：

import os
import sys
from jinja2 import FileSystemLoader, Environment

# 获取PEX运行时的根目录
pex_root = os.path.dirname(os.path.abspath(sys.argv[0]))
template_dir = os.path.join(pex_root, 'utils', 'tasks', 'templates')
env = Environment(loader=FileSystemLoader(template_dir))

• 保留-R参数重新打包即可。

方法三：清理重复配置 #

不要同时使用-R参数和setup包资源配置，二选一即可，避免资源重复放置引发路径混乱。

内容的提问来源于stack exchange，提问作者Leonardo Radillo escobar