Eel 版本演进全览:从 0.9 到 0.18 的核心功能变迁与源码实现解读

原创2026-10-14 12:10:111,822 阅读
文章标签:桌面应用Web框架前端

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 中一段可读的实现逻辑。

登录后查看全文
Eel