使用jinja2的packageloader加载模板时，若指定包名与当前运行脚本同名（如packageloader('basic')），python会尝试将其作为模块导入，导致basic.py被二次执行——这是由python包导入机制引发的隐式重入，而非代码逻辑错误。
使用jinja2的packageloader加载模板时，若指定包名与当前运行脚本同名（如packageloader('basic')），python会尝试将其作为模块导入，导致basic.py被二次执行——这是由python包导入机制引发的隐式重入，而非代码逻辑错误。
在CI流水线中运行Jinja2模板渲染脚本时出现“脚本执行两次”的现象，根本原因在于 PackageLoader 的设计语义：它专为从Python包（package）中加载模板而设计，其内部会通过 importlib.import_module() 动态导入指定名称的模块。当传入 PackageLoader('basic') 且当前目录下存在 basic.py 文件时，Python解释器会将该文件视为一个顶层模块（即 __main__ 模块），并在 PackageLoader 初始化过程中再次导入执行——这正是造成脚本重复运行的源头。
这种行为并非Bug，而是Python模块系统与Jinja2加载器契约的自然结果。PackageLoader 要求目标必须是一个合法的Python包（含 __init__.py），而非普通脚本文件。若强行将脚本名用作包名，就会触发模块重载，进而导致顶层代码（如print(...)、模板渲染等）被执行两次。
✅ 推荐解决方案：改用 FileSystemLoader
最简洁、安全且符合场景本质的方式是放弃 PackageLoader，改用 FileSystemLoader——它直接基于文件路径读取模板，完全绕过Python导入机制，杜绝重入风险：
#!/usr/bin/env python3
from jinja2 import Environment, FileSystemLoader, select_autoescape
# 直接指定模板所在目录（相对或绝对路径）
env = Environment(
loader=FileSystemLoader('templates'), # ← 指向 ./templates/
autoescape=select_autoescape()
)
result = env.get_template('basic_template.md').render({
'version': 'version123',
'date': 'some-date'
})
print(result)
✅ 优势：
- 无需创建额外文件（如空
__init__.py）； - 目录结构保持原样（
./templates/basic_template.md）； - 行为确定、跨平台一致，无隐式导入副作用；
- 更贴合“脚本渲染本地模板”的实际用途。
⚠️ 替代方案：正确构建Python包（仅当需真正打包分发时）
若项目未来需作为可安装包发布（如通过 pip install .），则应规范组织为包结构：
project/ ├── basic/ │ ├── __init__.py # 必须存在（可为空） │ └── templates/ │ └── basic_template.md ├── basic.py # 主入口脚本（不应与包同名！建议重命名为 main.py 或 cli.py） └── setup.py
此时 PackageLoader('basic') 才能安全工作，且 basic.py 不再与包名冲突。但对CI中单次渲染场景而言，此方案属于过度设计。
? 验证是否已修复
添加一行调试输出即可快速验证：
print(f"[DEBUG] Script PID: {os.getpid()}, __name__ = {__name__}")
正常执行时应仅输出一次，且 __name__ 恒为 '__main__'；若仍见两次输出，则说明仍有其他导入路径触发重入（如误将 basic.py 放入 PYTHONPATH 或被其他模块间接导入）。
总结
PackageLoader ≠ “任意目录加载器”，它是为已安装/可导入的Python包服务的；对于脚本级模板渲染任务，请始终优先选用 FileSystemLoader。这一选择不仅解决重复执行问题，更体现对工具职责边界的清晰认知——让文件系统做文件的事，让导入系统做模块的事。
