Python编译含AutoHotKey脚本为.exe时触发ValueError问题求助

我用Python开发了带GUI的AutoHotKey脚本，在VSCode中运行正常，但编译成.exe文件时出现如下报错：

Traceback (most recent call last):
File "test.pyw", line 14, in
ahk = AHK()
^^^^^
File "ahk_sync\engine.py", line 130, in init
File "ahk_sync\transport.py", line 610, in init
File "jinja2\loaders.py", line 323, in init
ValueError: The 'ahk' package was not installed in a way that PackageLoader understands.

已尝试的排查步骤：

• 多次卸载重装VSCode、Python和AutoHotKey
• 确认三者均为最新版本
• 更换不同版本的Autohotkey模块
• 添加所有相关文件夹路径至系统环境变量
• 通过ChatGPT、Youtube查找解决方案
• 检查site-packages目录

需求：正常运行生成的.exe文件，无需每次通过VSCode执行脚本。

解决方法 #

1. 打包时包含AHK模板资源（以PyInstaller为例） #

报错核心是打包后jinja2的PackageLoader找不到ahk包的模板文件，需手动将模板目录加入打包资源：

• 执行打包命令时添加--add-data参数：

  pyinstaller --add-data "C:\PythonXX\Lib\site-packages\ahk\templates;ahk\templates" test.pyw
  

  （将C:\PythonXX替换为你的Python安装路径，Windows用分号分隔路径，Linux/macOS用冒号）
• 若使用spec文件，在datas列表中添加：

  datas=[('path/to/site-packages/ahk/templates', 'ahk/templates')],
  

  再执行pyinstaller test.spec打包。

2. 替换PackageLoader为FileLoader #

修改ahk模块的transport.py文件：
找到初始化PackageLoader的代码，替换为FileLoader并指定模板绝对路径：

# 原代码（类似）
from jinja2 import PackageLoader
env = Environment(loader=PackageLoader('ahk', 'templates'))

# 修改为
from jinja2 import FileLoader
env = Environment(loader=FileLoader('C:/PythonXX/Lib/site-packages/ahk/templates'))

修改后重新打包（注意路径替换为你的实际路径）。

3. 用虚拟环境隔离依赖并打包 #

避免全局环境依赖冲突：

• 创建并激活虚拟环境：

  python -m venv venv
  venv\Scripts\activate  # Windows
  source venv/bin/activate  # Linux/macOS
  

• 重新安装依赖：

  pip install ahk pyinstaller
  

• 在虚拟环境中执行打包命令。

4. 重新通过pip安装AHK包 #

确保AHK包是正规pip安装，而非手动放置：

pip uninstall ahk
pip install ahk

安装完成后重新尝试打包。

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