使用 service worker 和 Pyodide 在浏览器中运行完整的服务端 Datasette Python 应用
2026年11月17日
Datasette Lite 是我将 Datasette Python 应用移植到浏览器中、通过 WebAssembly 和 Pyodide 直接运行的版本。我已发布基于 service worker 完全重写的 Datasette Lite,现在它几乎与真正的服务端应用难以区分。
你现在可以通过精心构造的 URL 访问 lite.datasette.io,完成以下所有操作:
- 加载客户端 Datasette,浏览任意 SQLite 数据库、JSON 文件、CSV 文件或 SQL 脚本
- 从 PyPI 选择已发布的 Datasette 版本进行加载
- 从 Datasette GitHub 仓库加载特定 commit、tag 或分支名
- 从 100 多个 SQLite 版本中选择一个与 Datasette 搭配使用
- 从 PyPI 安装额外的 Datasette 插件,或通过 URL 安装 wheel 文件,包括 JavaScript 可视化工具
能够加载特定的 Datasette 引用、插件和 SQLite 版本,使这个工具非常适合链接到进行中功能的演示或 bug 复现,而无需启动完整的 Web 服务器来托管该演示。
举个例子,考虑以下 URL:
https://lite.datasette.io/?install=datasette-maplibre&url=https://gist.githubusercontent.com/simonw/39fa5d399465766039549912e2b3d291/raw/f6dfba99a75cbb8b5d9386223220eb52272767ee/demo.db&metadata=https://gist.githubusercontent.com/simonw/39fa5d399465766039549912e2b3d291/raw/f6dfba99a75cbb8b5d9386223220eb52272767ee/metadata.yml#/demo/capitals_and_countries%23map=0/4.2/180&color=continent
点击该链接,经过短暂的加载界面后,你将看到一个类似这样的页面:

这就是 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 头——我将这样的文件托管在 Gist 中,因为它们为 Web 托管的文件提供了获取开放 CORS 头的简便方式。
&metadata=https://.../metadata.yml 加载这个 metadata.yml 文件。metadata 文件为各种表以及 Datasette 首页添加 HTML 描述。访问该首页,可查看该插件其他功能的引导式导览,所有这些都定义在 metadata 文件中。
#/demo/capitals_and_countries%23map=0/4.2/180&color=continent 是一个片段哈希,它会转换为 Datasette 中的一个位置——这里加载的是 /demo/capitals_and_countries SQL 视图,然后向它追加另一个片段哈希(%23 是 URL 编码的 #),该哈希告诉地图插件缩放到某个位置,并依据数据中的 continent 列设置地图上形状的颜色。
这个 URL 做了很多工作!我去年在 URL-addressable Pyodide Python environments 中写过更多关于这种构建 URL 可寻址软件技巧的内容。
支持的 URL 参数完整集合在 Datasette Lite README 中有描述。
我已经开始将 Datasette Lite 作为 Datasette 开发流程的一部分来使用。这里有一个最近描述分页 bug 的 issue——我在那里发布了一条评论,用指向 Datasette Lite 的链接演示了旧的、有问题的行为以及新的修复:
Demo of the bug: https://lite.datasette.io/?ref=1.0a42&sql=https://gist.github.com/simonw/75ececf61d50e6e8d50f0c150150ee81#/data/scores?_size=2&_sort=score—click next and the second page is empty. Here’s that same page with the bug fixed (running on 1.0a43): https://lite.datasette.io/?ref=1.0a43&sql=https://gist.github.com/simonw/75ececf61d50e6e8d50f0c150150ee81#/data/scores?_size=2&_sort=score
Demo of the bug: https://lite.datasette.io/?ref=1.0a42&sql=https://gist.github.com/simonw/75ececf61d50e6e8d50f0c150150ee81#/data/scores?_size=2&_sort=score—click next and the second page is empty.
Here’s that same page with the bug fixed (running on 1.0a43): https://lite.datasette.io/?ref=1.0a43&sql=https://gist.github.com/simonw/75ececf61d50e6e8d50f0c150150ee81#/data/scores?_size=2&_sort=score
这是如何工作的,使用 service workers
Datasette Lite 并不是一个新项目。我在 2022 年发布了第一个版本,最初多少有点开玩笑的意味(在浏览器中运行服务端应用相当有趣),但它很快就证明了自身的价值。
最初版本的问题在于它只是一个 hack。它的工作方式是在 Pyodide web worker 中运行 Datasette,通过该栈模拟请求,然后使用 innerHTML 将生成的 HTML 注入回顶层页面。
这对基础 Datasette 有效,但意味着任何使用 JavaScript 的功能都无法工作,因为 innerHTML 中的 script 标签不会执行,而且它使用的 web worker 技巧无法加载额外的 JavaScript 或 CSS 文件。
新版本采用了基于 Service Workers 的全新方法。这些允许 JavaScript 拦截对新页面和资源的 HTTP 请求,并从客户端代码中提供它们。
Datasette Lite 为整个 lite.datasette.io 域注册了一个 service worker。父页面随后创建一个 iframe,将 Datasette 页面的请求发送到如下所示的 URL:
/app/aa94e6851595/ # the homepage (HTML)
/app/aa94e6851595/data/places # a table page (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 尝试配置什么插件或其他设置。
相反,父页面生成一个随机会话 ID,并将其用作所有后续隐藏资源和页面加载的前缀。service worker 随后可以使用该会话 ID 将这些请求通过父页面路由回一个 web worker,该 web worker 为该特定会话运行一个专用的 Datasette 实例。
(我们仍然需要一个 web worker,因为 service worker 中的 Pyodide 无法在约 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 版本。自那以后又发布了 87 个版本。
能够针对特定版本的 SQLite 启动 Datasette,对于演示新的 SQLite 功能和调试奇怪的问题非常有用。
过去,我使用各种技巧在我的 Mac 上让不同版本的 SQLite 与 Python 一起运行,但这不是一个简单的过程。
WebAssembly 非常适合这个。我可以完全在浏览器中加载自定义的 SQLite 构建,在那里测试它,然后关闭标签页时将其丢弃。
datasette/pysqlite3-wasm-wheels 是我的新仓库,其中包含针对 163 个不同 SQLite 版本的 pysqlite3 的 WebAssembly 编译的 Python wheel。每个版本都有一个类似这样的文件名:
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 文件的路径,然后获取该 wheel 并将其安装到 Pyodide 环境中,并配置 Datasette 使用它。
构建完 wheel 后,我决定让 Claude Fable 5.2 为我构建这个附加工具,用于在任意选定的 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 扩展过去是这类事情的阻碍,但现在任何优秀的编码 agent 都能把它们编译成与 Pyodide 兼容的 WebAssembly。截至 2026 年 4 月的 PEP 783,你甚至可以把它们发布到 PyPI。
一个问题是数据库。SQLite 完全没问题,但在 WebAssembly 中运行 PostgreSQL 或 MySQL 虽然可行,仍是一条人迹罕至的路。
我很想看到这样的 WebAssembly 预览环境成为整个 Python 生态中一种常见的模式。
致 Hacker News:Full server-side Datasette Python app in the browser with service workers
更多近期文章
- 用 Claude 定位神秘哔声的来源 - 2026 年 11 月 9 日
- 把你的垃圾 PR 描述藏在 <details><summary> 后面 - 2026 年 11 月 9 日
- 我笔记本上的 Qwen 3.8 27B 也能解读模型权重 - 2026 年 11 月 3 日
- 美国人口普查局与“超级智能” - 2026 年 11 月 2 日