Eel 版本演进全览:从 0.9 到 0.18 的核心功能变迁与源码实现解读
Eel 版本演进全览:从 0.9 到 0.18 的核心功能变迁与源码实现解读
导读
本文以官方 CHANGELOG.md 为骨架,系统梳理 Eel(一个用于构建类 Electron 的 HTML/JS 桌面 GUI 的小型 Python 库)从 0.9 到 0.18 的版本演进主线,并结合仓库内 eel/init.py、eel/browsers.py、eel/chrome.py、eel/edge.py、eel/msIE.py、setup.py 等源码逐项印证。读完本文,你将掌握 Eel 各版本引入的浏览器支持(Chrome/Edge/IE/Electron)、启动参数(app、disable_cache、all_interfaces、shutdown_delay、default_path、js_result_timeout)、Jinja 模板、PyParsing 函数解析、中间件扩展、PyInstaller 打包等能力的来龙去脉,并能据此为项目选择合适的版本与配置方案。
一、版本脉络总览
从 CHANGELOG 记录的版本时间线看,Eel 的功能演进大致可分为三个阶段:
- 0.9.x ~ 0.11.x(功能奠基期):补齐 Jinja 模板、Electron 名称冲突规避、Edge 支持、中间件注入、
disable_cache/all_interfaces参数等基础能力; - 0.12.x ~ 0.15.x(稳健成熟期):引入
js_result_timeout超时控制、macOS Chromium 探测、spawn()返回 greenlet、shutdown_delay、register_eel_routes、全面类型注解,并升级 Bottle 以修复安全 CVE; - 0.16.x ~ 0.18.x(现代化收尾期):提升 Python 版本下限、新增 IE 与 Edge app_mode、将资源读取从
pkg_resources迁移到importlib.resources。
下面按主题维度展开,将 CHANGELOG 中的条目与源码一一对应。
二、安装、依赖与 Python 版本要求
2.1 从 Python 3.6 到 3.7+ 的下限提升
- v0.16.0:放弃对 Python 3.7 以下版本的支持;
- v0.13.0:放弃对 Python 3.6 以下版本的支持;
- v0.17.0:新增对 Python 3.11 与 3.12 的支持。
当前仓库的 setup.py 中明确声明 python_requires='>=3.7',与上述演进一致。这意味着采用 Eel 新版本时,项目的 Python 环境至少应为 3.7。
2.2 可选依赖:eel[jinja2] 与运行时依赖清单
- v0.13.0:引入
pip install eel[jinja2]的 extras 安装方式,把 Jinja2 从强制依赖改为可选依赖。
对应到 setup.py:
extras_require={
"jinja2": ['jinja2>=2.10']
},
与此同时,setup.py 的 install_requires 目前包含:
install_requires=['bottle', 'bottle-websocket', 'future', 'pyparsing', 'typing_extensions', 'importlib_resources'],
其中两个条目直接来自 CHANGELOG 的修复记录:
- v0.18.1:修复安装时缺少
typing_extensions的问题,将其加入安装依赖。源码中 eel/init.py 的from typing_extensions import Literal以及 eel/types.py 的Literal, TypedDict, TypeAlias均依赖该包,且 eel/types.py 的注释说明这是为了兼容 Python < 3.10 不支持TypeAlias的场景; - v0.15.1:将 Bottle 依赖从 0.12.13 提升至 0.12.20,以修复严重级漏洞 CVE-2022-31799 与中等级漏洞 CVE-2020-28473。这一条提醒我们:Eel 的 Web 服务端完全构建在 Bottle 之上(eel/init.py 调用
btl.run),因此 Bottle 的安全更新对 Eel 应用至关重要。
2.3 资源读取方式迁移:pkg_resources → importlib.resources
- 0.18.2:从
pkg_resources切换到importlib.resources。
这是本版本最重要的内部改造。pkg_resources(setuptools 的一部分)已被上游标记为弃用,迁移到标准库生态的 importlib.resources 后,前端桥接脚本的读取逻辑变为(eel/init.py):
_eel_js_reference = importlib_resources.files('eel') / 'eel.js'
with importlib_resources.as_file(_eel_js_reference) as _eel_js_path:
_eel_js: str = _eel_js_path.read_text(encoding='utf-8')
这里读取的 eel.js 会被动态注入到每个页面(eel/init.py 中 /eel.js 路由会替换其中的占位符后返回),是整个前后端通信机制的基础。值得注意的是,eel/main.py 中的 PyInstaller 打包入口仍使用 pkg.resource_filename('eel', 'eel.js') 定位该文件——打包场景与运行时资源读取走的是两条路径。
三、浏览器支持的演进
3.1 浏览器模块体系
Eel 通过 eel/browsers.py 维护一个浏览器模块注册表:
_browser_modules: Dict[str, ModuleType] = {'chrome': chm,
'electron': ele,
'edge': edge,
'msie': ie}
eel.start(mode=...) 支持的值包括 'chrome'、'electron'、'edge'、'msie'、'custom',也可以传 None 或 False 不打开任何窗口(eel/browsers.py)。若指定的浏览器找不到安装路径,会抛出 EnvironmentError("Can't find %s installation");同时可用 eel.browsers.set_path(name, path) 手动指定可执行文件路径。
3.2 Microsoft Edge:从「非 Windows 禁用」到「app_mode 支持」
- v0.11.0:新增对 Microsoft Edge 的支持;
- v0.13.0:在非 Windows 平台禁用 Edge,直到实现完善的支持;
- v0.18.0:在 Edge 中新增
app_mode支持。
这三条记录对应 eel/edge.py 的实现:find_path() 仅在 platform.system() == 'Windows' 时返回 True(eel/edge.py),这与 v0.13.0 的「非 Windows 禁用」一致;而 eel/edge.py 的 run() 会根据 options['app_mode'] 选择 start msedge --app=<url> 还是 start msedge --new-window <url>,这正是 v0.18.0 引入的 app_mode 能力。
配套示例 examples/01 - hello_world-Edge/hello.py 展示了两种用法:在 Windows 10 及以上平台直接 eel.start('hello.html', mode='edge'),或在 Chrome 缺失时把 Edge 作为回退方案。
3.3 MS Internet Explorer 支持
- v0.18.0:新增对 MS Internet Explorer 的支持(PR #744)。
对应新增模块 eel/msIE.py:run() 通过 start microsoft-edge:{url} 命令启动(实际映射到 Edge 内核),find_path() 同样只承认 Windows 平台。因此该模式的实际可用环境是 Windows 系统。
3.4 Chrome/Chromium:跨平台查找与 Windows 路径校验
Chrome 是 Eel 的默认浏览器(mode 默认 'chrome')。围绕它有三个版本记录:
- v0.12.1:修复 Windows 上盲目返回 Chrome 路径的 bug,先确认路径指向的文件真实存在;
- v0.12.3:在 macOS 上搜索 Chromium;
- v0.11.0 相关能力:默认以 App Mode(
--app命令行参数)启动。
源码证据位于 eel/chrome.py:
find_path()按平台分派(eel/chrome.py):Windows 走注册表查询,macOS 走默认路径 +mdfind搜索(eel/chrome.py),Linux 依次探测chromium-browser、chromium、google-chrome、google-chrome-stable(eel/chrome.py);- Windows 查找逻辑中,查询注册表后会执行
if not os.path.isfile(chrome_path): continue的校验(eel/chrome.py),这正是 v0.12.1 修复点的落实; _find_chromium_mac()(eel/chrome.py)即 v0.12.3 的成果;run()在app_mode=True时拼接<a href="https://link.gitcode.com/i/dcc55e937c0b4c782f016edfe642232f" target="_blank">path, '--app=%s' % url] + cmdline_args([eel/chrome.py)。
3.5 Electron 与名称冲突规避
- v0.10.1:避免使用 Electron 时的名称冲突,使 jQuery 等库正常工作。
原因在于 Electron 的 Node.js 环境会向页面注入 require、module、exports 等全局对象,干扰浏览器端库。修复位于 eel/eel.js:
if(typeof require !== 'undefined'){
// Avoid name collisions when using Electron, so jQuery etc work normally
window.nodeRequire = require;
delete window.require;
delete window.exports;
delete window.module;
}
示例 examples/09 - Eelectron-quick-start/hello.py 演示了 mode='electron' 的启动方式,并注释了 mode='custom' 手动指定 Electron 可执行文件的写法。
四、eel.start() 启动参数的系统性扩展
eel.start() 是 Eel 最核心的 API。CHANGELOG 中多个版本为它新增了参数,当前完整签名见 eel/init.py,参数类型在 eel/types.py 的 OptionsDictT 中统一定义。下面按引入版本梳理。
4.1 v0.11.0:app、disable_cache、all_interfaces
app:覆盖 Eel 使用的 Bottle 实例,允许开发者在交给 Eel 之前注入任意中间件(会话管理、认证等)。源码中,若传入的是btl.Bottle实例则自动注册路由,否则回退到btl.default_app()并需手动调用register_eel_routes(eel/init.py);disable_cache:默认禁用页面缓存。该参数通过 eel/init.py 的_set_response_headers()生效——当其为真时,为所有响应设置Cache-Control: no-store头;同时 Chrome 的默认cmdline_args也包含<a href="https://link.gitcode.com/i/ea1b267334dcc831105d4927c2d88ca9" target="_blank">'--disable-http-cache']([eel/init.py)。示例 examples/08 - disable_cache/disable_cache.py 特别说明:disable_cache现已默认为True,显式传入主要是为了将其置回False以启用缓存;all_interfaces:让 Bottle 服务器监听所有网络接口。实现位于 eel/init.py:为真时HOST = '0.0.0.0'。
4.2 v0.12.0:js_result_timeout(eel.init 参数)
- v0.12.0:允许用户覆盖 Python 等待 JS 函数执行返回的时长,超时后返回
None。
该参数属于 eel.init() 而非 eel.start(),默认值 10000 毫秒(eel/init.py 注释与 eel/init.py 签名)。同步等待逻辑在 _call_return()(eel/init.py):不带回调调用时,最多以 1ms 粒度轮询 _js_result_timeout 次;传回调则注册到 _call_return_callbacks 异步返回。README 也说明该超时只存在于 Python 侧,JS 侧没有对应超时。
4.3 v0.13.2:default_path
- v0.13.2:新增
default_path参数,定义访问根 URL 时默认取出的文件。
实现为 eel/init.py 的 _root() 路由:默认 'index.html',且会校验其类型必须为 str。
4.4 v0.15.0:shutdown_delay
- v0.15.0:为
start()新增shutdown_delay参数(PR #529),默认 1.0 秒。
它服务于 Eel 的关机检测机制:任一 websocket 关闭后,Eel 等待 shutdown_delay 秒再检查是否还有存活连接,若没有则退出程序(eel/init.py):
_shutdown = gvt.spawn_later(_start_args['shutdown_delay'], _detect_shutdown)
_detect_shutdown() 在 len(_websockets) == 0 时调用 sys.exit()(eel/init.py),且 shutdown_delay 必须为数字否则抛 ValueError(eel/init.py)。该机制还支持「关窗后先展示告别页再退出」的玩法(配合 close_callback 与 eel.show(),见 eel/init.py 的 docstring 示例)。v0.13.1 的「websocket 关闭时不再激进关闭 Eel 服务器」(#337)正是这一延迟检测机制的早期雏形。
4.5 窗口几何参数:size、position、geometry
这三个参数共同控制窗口尺寸与位置(size/position 作用于主窗口,geometry 按页面路径细分)。它们在运行时被注入 eel/eel.js 的 _position_window(),最终调用浏览器端的 window.resizeTo / window.moveTo。注入过程见 eel/init.py 的 _eel() 路由。
五、自定义应用与中间件:app 参数与 register_eel_routes
- v0.11.1:修复 #203 的问题,允许用户把自己的 Bottle 实例传入 Eel;
- v0.12.2:修复阻止通过自定义 Bottle 使用中间件的 bug;
- v0.15.2:新增
register_eel_routes,用于把 Eel 路由应用到非 Bottle 的自定义 app 实例。
三者共同勾勒出「Eel 可嵌入既有 Web 应用」的能力边界。Eel 的全部路由集中在 eel/init.py 的 BOTTLE_ROUTES 字典(/eel.js、/、/<path:path>、/eel),而 eel/init.py 的 register_eel_routes() 负责把它们注册到任意 app 上。docstring 中给出了与 Beaker 会话中间件结合的典型用法:
app = bottle.Bottle()
eel.register_eel_routes(app)
middleware = beaker.middleware.SessionMiddleware(app)
eel.start(app=middleware)
示例 examples/10 - custom_app_routes/custom_app.py 展示了同时存在自定义路由(/custom)与 Eel 路由的应用形态。
六、JS 函数解析引擎:从正则到 PyParsing
- v0.14.0:将 JS 函数名解析从正则改为 PyParsing(由 @KyleKing 贡献)。
eel.init() 会遍历 allowed_extensions 指定的文件(默认 <a href="https://link.gitcode.com/i/7acbad275f7b4c4a02d5e337984e4e2b" target="_blank">'.js', '.html', '.txt', '.htm', '.xhtml', '.vue']),扫描其中所有 eel.expose(...) 调用,把暴露的函数名收集为 Python 侧可调用的 JS 函数。解析语法定义在 [eel/init.py:
EXPOSED_JS_FUNCTIONS: pp.ZeroOrMore = pp.ZeroOrMore(
pp.Suppress(
pp.SkipTo(pp.Literal('eel.expose('))
+ pp.Literal('eel.expose(')
+ pp.Optional(
pp.Or([pp.nestedExpr(), pp.Word(pp.printables, excludeChars=',')]) + pp.Literal(',')
)
)
+ pp.Suppress(pp.Regex(r'["\']?'))
+ pp.Word(pp.printables, excludeChars='"\')')
+ pp.Suppress(pp.Regex(r'["\']?\s*\)')),
)
相比正则,PyParsing 语法能正确处理嵌套表达式(如 eel.expose(function(e){console.log(e)},"name"))与压缩混淆后的代码。测试 tests/unit/test_eel.py 用参数化用例覆盖了普通调用、匿名函数、带缩进换行的调用、压缩 JS(minified.js)、HTML 与 TSX 文件等多种形态,并验证 eel.init() 能正确收集全部函数名。
七、Jinja2 模板引擎
- v0.9.13:新增对 Jinja 模板的支持;
- v0.10.2:仅从声明的 Jinja 模板目录渲染模板;
- v0.10.3:修复不使用 Jinja 模板时无法使用 Eel 的 bug;
- v0.10.0:修复示例 06 的 bug,明确
templates/jinja_templates参数接收的是文件路径而非布尔值。
当 eel.start(..., jinja_templates='templates') 传入目录名时,eel/init.py 会用 jinja2.Environment + FileSystemLoader 构建模板环境(autoescape 仅对 html/xml 开启),且会严格校验参数必须是 str(否则抛 TypeError)。渲染发生在 _static() 路由(eel/init.py):只有请求路径以 jinja_templates + '/' 为前缀时才走模板渲染,其余路径仍按静态文件服务——这正是 v0.10.2「仅从声明目录渲染」的约束。
配套示例 examples/06 - jinja_templates/hello.py 展示了模板目录与 jinja_templates='templates' 的完整用法。
八、异步基础设施:Gevent 与 greenlet
- v0.12.4:
spawn()返回 greenlet 任务(PR #300);同时为.js文件设置正确 MIME 类型以减少 Windows 上的报错(PR #289)。
Eel 的事件循环建立在 Gevent 之上。eel/init.py 的 spawn() 直接 return gvt.spawn(function, *args, **kwargs)——返回 greenlet 意味着调用方可以持有句柄进行 join()、kill() 等控制;sleep() 则包装 gevent.sleep()(eel/init.py)。README 提醒:如果需要 monkey patch,必须在 import eel 之前调用 gevent.monkey.patch_all(),并且建议用 eel.sleep() 而非 time.sleep()。
MIME 类型修复对应 eel/init.py:mimetypes.add_type('application/javascript', '.js')。
九、版本兼容与选型建议
9.1 版本要求小结
| 版本 | 关键变更 | 仓库证据 |
|---|---|---|
| 0.18.2 | importlib.resources 替换 pkg_resources |
eel/init.py |
| 0.18.1 | 依赖补充 typing_extensions |
setup.py |
| 0.18.0 | MSIE 支持、Edge app_mode、类型注解改进 | eel/msIE.py、eel/edge.py、eel/types.py |
| 0.17.0 | Python 3.11/3.12 支持 | tox.ini |
| 0.16.0 | Python 下限提升至 3.7 | setup.py |
| 0.15.3 | 全面类型提示 | py.typed、eel/types.py |
| 0.15.2 | register_eel_routes |
eel/init.py |
| 0.15.1 | Bottle 升级修复 CVE | setup.py |
| 0.15.0 | shutdown_delay |
eel/init.py |
| 0.14.0 | PyParsing 函数解析 | eel/init.py |
| 0.13.2 | default_path |
eel/init.py |
| 0.13.0 | eel[jinja2] extra;非 Windows 禁用 Edge |
setup.py、eel/edge.py |
| 0.12.x | js_result_timeout、Chromium(macOS)、spawn() 返回 greenlet |
eel/init.py |
| 0.11.x | app、disable_cache、all_interfaces、Edge |
eel/init.py |
| 0.9.x-0.10.x | Jinja 模板、Electron 冲突规避 | eel/eel.js |
9.2 注意维护状态与安全前提
本仓库 README.md 以醒目警告声明:该项目事实上已处于停止维护状态,多年未获常规更新。因此在选择 Eel 作为技术方案时,应结合 setup.py 中 Development Status :: 3 - Alpha 的成熟度标识,认真评估自身应用的安全性维护策略。若需了解开发环境搭建与测试方式,可参考 README-developers.md(包含 venv 创建、tox 多版本测试等说明)与 tests/conftest.py(基于 Selenium + ChromeDriver 的集成测试基础设施,示例运行方式见 tests/utils.py 的 get_eel_server())。
十、结语
从 CHANGELOG.md 这十几条记录中,可以看到一个小型 GUI 库的完整成长轨迹:它逐步补齐了浏览器生态覆盖(Chrome/Chromium → Edge → IE → Electron)、丰富了启动参数以适配真实桌面应用需求(中间件、缓存控制、关机检测、默认页、超时控制)、强化了工程化能力(类型注解、PyParsing 解析、依赖安全升级、标准库迁移)。这些历史演进不仅是使用 API 时的查询手册,更是理解 Eel「Bottle + Gevent + WebSocket + 浏览器进程」架构设计的绝佳素材——每一个参数背后,都对应着 eel/init.py 中一段可读的实现逻辑。