用 service workers 和 Pyodide 在浏览器中运行完整的 Datasette Python 服务端应用
用 service workers 和 Pyodide 在浏览器中运行完整的 Datasette Python 服务端应用
2026年11月17日
Datasette Lite 是我把 Datasette Python 应用移植到浏览器里直接运行的成果,基于 WebAssembly 和 Pyodide。现在我用 service workers 对 Datasette Lite 做了彻底重写,新版几乎和真正的服务端应用别无二致。
现在通过精心构造的 lite.datasette.io URL,你可以实现以下所有操作:
- 加载客户端版 Datasette,浏览任意 SQLite 数据库、JSON 文件、CSV 文件或 SQL 脚本
- 从 PyPI 选择指定发布版本的 Datasette 来加载
- 从 Datasette 的 GitHub 仓库加载指定的 commit、tag 或分支
- 从 100 多个 SQLite 版本中任选一个配合 Datasette 使用
- 从 PyPI 或 wheel 文件 URL 安装额外的 Datasette 插件,包括 JavaScript 可视化工具
能够加载指定的 Datasette 版本、插件和 SQLite 版本,让它成为链接演示的绝佳工具——无论是展示开发中的新功能还是复现 bug,都不再需要为此专门搭一个 web 服务器。
举个例子,看看下面这个 URL:
点开这个链接,经过短暂加载后,你会看到一个这样的页面:

这是 Datasette 正在运行新的 datasette-maplibre 插件,加载包含国家 GeoJSON 形状数据的数据库,并在表格中同时展示合并地图和单个边界地图。
让我们来拆解一下这个 URL,看看它在做什么:
https://lite.datasette.io/
?install=datasette-maplibre
&url=https://.../demo.db
&metadata=https://.../metadata.yml
#/demo/capitals_and_countries%23map=0/4.2/180&color=continent
?install=datasette-maplibre 会从 PyPI 安装该额外插件。你可以多次传入 &install=... 以加载更多插件。
&url=https://.../demo.db 会从提供的 URL 加载该 SQLite 数据库。这些 URL 需要具备开放的 CORS 头——我会将此类文件托管在 Gists 上,因为它们为网页托管的文件提供了一种获取开放 CORS 头的简便方式。
&metadata=https://.../metadata.yml 会加载这个 metadata.yml 文件。元数据文件为多个数据表和 Datasette 首页添加了 HTML 描述。访问这个首页,可以看到该插件的其他功能导览,全部通过元数据文件定义。
#/demo/capitals_and_countries%23map=0/4.2/180&color=continent 是一个片段哈希,它会被转换为 Datasette 内部的路径——这里加载的是 /demo/capitals_and_countries SQL 视图,然后在其后附加另一个片段哈希(%23 是 URL 编码后的 #),告诉地图插件缩放到指定位置,并根据数据中的 continent 列设置地图上图形的颜色。
这个 URL 承载了相当多的功能!关于这种构建可通过 URL 寻址的软件的技巧,我去年在URL-addressable Pyodide Python environments 一文中有更详细的介绍。
Datasette Lite 支持的全部 URL 参数说明见 Datasette Lite README。
我已经开始把 Datasette Lite 用于 Datasette 的开发流程。比如最近的一个 issue 描述了一个分页 bug——我在评论中用 Datasette Lite 的链接演示了修复前的错误行为和修复后的效果:
Bug 演示:https://lite.datasette.io/?ref=1.0a42&sql=https://gist.github.com/simonw/75ececf61d50e6e8d50f0c150150ee81#/data/scores?_size=2&_sort=score——点击下一页,第二页是空的。
修复该 bug 后的同一页面(运行于 1.0a43 版本):https://lite.datasette.io/?ref=1.0a43&sql=https://gist.github.com/simonw/75ececf61d50e6e8d50f0c150150ee81#/data/scores?_size=2&_sort=score
原理:利用 Service Worker
Datasette Lite 并非全新项目。我早在 2022 年就发布了首个版本,最初只是觉得把服务端应用跑在浏览器里挺有趣,是个玩笑,但很快它便展现出实际价值。
初版的问题在于它只是个临时方案。其实现方式是让 Datasette 在 Pyodide web worker 中运行,模拟请求经过该技术栈处理,再通过 innerHTML 将生成的 HTML 注入顶层页面。
对于基础功能的 Datasette,这套方法可行;但所有依赖 JavaScript 的功能都会失效,因为 innerHTML 中的 script 标签不会执行,且用于 web worker 的变通方法无法加载额外的 JavaScript 或 CSS 文件。
新版本采取了基于 Service Worker 的完全不同思路。它允许 JavaScript 拦截针对新页面和资源的 HTTP 请求,转由客户端代码直接响应。
Datasette Lite 为整个 lite.datasette.io 域名注册了 service worker。父页面随后创建一个 iframe,将针对 Datasette 页面的请求发送至如下形式的 URL:
/app/aa94e6851595/ # 主页(HTML)
/app/aa94e6851595/data/places # 表格页面(HTML)
/app/aa94e6851595/-/static/navigation-search.js #(JavaScript)
/app/aa94e6851595/-/static/app.css #(CSS)
这些是常规的 Datasette URL,但加了 /app/aa94e6851595/ 前缀。这是为了什么?
加入 /app/<session>/ 前缀,主要是为了解决多标签页并存的问题。
以上述 URL 为例,它加载了一个带有 datasette-maplibre 插件的演示实例。该 URL 定义了一个完整的定制 Datasette 实例。你可能在一个标签页中运行这个实例,同时在另一个标签页运行我其他的演示链接。
lite.datasette.io 的 service worker 由所有标签页共享。如果它把请求路由到同一个 Datasette 实例,那么无论各标签页的 URL 想配置什么插件或设置,它们都会共享同一个底层实例。
因此,父页面会生成一个随机的 session ID,作为后续所有隐藏资源加载和页面加载的前缀。service worker 再借助这个 session ID,把请求经父页面转发给一个 web worker——里面运行着该会话专属的 Datasette 实例。
(依然需要 web worker,因为取决于浏览器,Pyodide 在 service worker 里最多只能维持 30 秒左右的状态。这里的环节实在太多了!)
我让 Claude Fable 5.2 生成了几张 SVG 示意图来解释这套机制。下面是我最喜欢的一张,现已嵌入 Datasette Lite 的 README:
这个系统最早可以追溯到今年 5 月,当时它是一个使用 Claude Opus 4.8 生成的AI 研究性验证项目。直到 11 月(配合 Claude Fable 5.2),我才对这套机制足够熟悉,从而有信心将其投入生产环境!
附加功能:选择 SQLite 版本
我昨晚添加了这一功能,这是我在调查SQLite 中一个潜在 Bug过程中产生的延伸成果。
Datasette 设计用于兼容自 3.25 版本(2018 年 9 月发布)以来任何已发布的 SQLite 版本。自那时起,SQLite 又发布了 87 个新版本。
能够针对特定版本的 SQLite 启动 Datasette,对于演示 SQLite 新特性和排查奇怪的问题非常有用。
过去我用过各种技巧在 Mac 上让 Python 运行不同版本的 SQLite,但这个过程并不简单。
WebAssembly 正好适合这个场景。我可以在浏览器里加载一个自定义编译的 SQLite,直接测试,关掉标签页就丢弃。
datasette/pysqlite3-wasm-wheels 是我的新仓库,包含针对 pysqlite3 编译的 WebAssembly Python wheel,覆盖 163 个不同的 SQLite 版本。每个版本对应一个类似这样的文件:
pysqlite3-0.6.2-3.54.1-cp314-cp314-pyemscripten_2026_0_wasm32.whl
这是最新版本 SQLite 3.54.1 的。
Datasette Lite 现在支持一个特殊的 ?sqlite= URL 参数,可以接受 3.54.1 这样的版本号,解析出对应 wheel 文件的路径,然后下载并安装到 Pyodide 环境中,再配置 Datasette 使用它。
构建好这些 wheel 之后,我让 Claude Fable 5.2 帮我做了[这个附加工具](https://datasette.github.io/pysqlite3-wasm-wheels/?versions=3.54.1,3.54.0&sql=select+json_object(%27a%27%2C+(select+json_array(1%29%29%29),可以在任意选定的 SQLite 版本之间对比 SQL 查询结果。下面这个例子展示了 select json_object('a', (select json_array(1))) 在 SQLite 3.54.0 和 3.54.1 之间的差异:
这对其他 Python 应用也应同样适用
Datasette Lite 的工作机制并非 Datasette 独有。几乎任何 Python 应用都应该能采用同样的技巧——完全在浏览器中通过 WebAssembly 和 Pyodide 运行,以此作为低成本手段来提供预览环境、展示功能以及复现 Bug。
C 语言和 Rust 编写的扩展过去曾是此类方案的阻碍,但现在任何优秀的编程代理都能将它们编译为 Pyodide 兼容的 WebAssembly。根据 2026 年 4 月发布的 PEP 783,你甚至可以将它们发布到 PyPI。
其中一个难点是数据库。SQLite 完全没问题,但要在 WebAssembly 中运行 PostgreSQL 或 MySQL,虽然可行,却仍是一条少有人走的路。
我非常期待这类 WebAssembly 预览环境能在整个 Python 生态中成为一种常见模式。
面向 Hacker News:在浏览器中通过 service workers 运行完整的服务器端 Datasette Python 应用