Datasette Lite:用 Pyodide 和 Service Worker 在浏览器运行 Python 应用
把服务端 Python 应用放进浏览器,难点不只是让 Python 代码跑起来,还包括页面导航、JavaScript、CSS、应用状态和多标签页之间的隔离。
Datasette Lite 的重写围绕这些问题展开:使用 Pyodide 执行 Python,用 Service Worker 接管页面与静态资源请求,再由独立的 Web Worker 运行 Datasette 实例。
一个 URL 配置一套演示环境
Datasette Lite 是 Datasette 的浏览器版本,通过 WebAssembly 和 Pyodide 在客户端运行。用户可以通过 URL 配置:
- 加载 SQLite 数据库、JSON、CSV 或 SQL 脚本。
- 从 PyPI 选择已发布的 Datasette 版本。
- 加载 Datasette 仓库中的特定提交、标签或分支。
- 选择不同版本的 SQLite。
- 从 PyPI 或 wheel 文件地址安装插件,包括 JavaScript 可视化插件。
这使它适合分享开发中的功能,或构建缺陷复现环境:接收者打开链接,就能加载指定的数据、版本和插件,而不必为这次演示单独部署应用服务器。
关键参数如何分工
| 参数或 URL 部分 | 用途 |
|---|---|
install |
安装插件,可重复指定以加载多个插件 |
url |
加载数据库等数据文件 |
metadata |
加载元数据文件,为首页、表等添加描述 |
ref |
指定 Datasette 版本或代码引用 |
sql |
加载 SQL 脚本 |
sqlite |
指定 SQLite 版本 |
# 后的片段 |
定位 Datasette 内部页面,并携带页面状态 |
远程数据文件需要允许跨域读取,即配置合适的 CORS 响应头。 在浏览器里运行应用,并不意味着可以绕过浏览器的跨域限制。
以 datasette-maplibre 插件为例,一套 URL 配置可以同时完成插件安装、数据库加载、元数据加载和地图定位。数据库中的国家 GeoJSON 几何数据,既能显示在综合地图上,也能在表格单元格中显示单独的边界地图。
地图的视角和着色字段也可以包含在地址片段中。若内部页面还需要自己的 #,则可用 %23 表示编码后的井号。
为什么要从 innerHTML 改为 Service Worker
2022 年推出的早期版本,已经能在 Pyodide Web Worker 中运行 Datasette。其做法是模拟请求,再把返回的 HTML 通过 innerHTML 注入顶层页面。
这种方式能支持基础页面,却难以完整支持前端功能:
- 通过
innerHTML插入的脚本标签不会执行。 - 额外的 JavaScript 和 CSS 文件无法按应用原有方式正常加载。
新版不再仅仅把 HTML 填进页面,而是让 Service Worker 拦截页面和资源请求,并返回客户端生成的响应。浏览器因此可以按常规方式处理 HTML、脚本和样式。
请求如何在浏览器内流转
顶层页面创建一个 iframe,用于显示 Datasette 页面。iframe 访问的路径带有会话前缀,例如:
/app/aa94e6851595/
/app/aa94e6851595/data/places
/app/aa94e6851595/-/static/navigation-search.js
/app/aa94e6851595/-/static/app.css
一次请求的处理流程是:
- iframe 请求
/app/<session>/…下的页面或资源。 - Service Worker 拦截请求,根据会话标识找到对应的顶层页面。
- 顶层页面将请求转发给自己的 Web Worker。
- Web Worker 中的 Pyodide 运行 Python,通过 ASGI 桥接调用 Datasette,并查询 SQLite。
- 状态码、响应头和响应体沿相反路径返回。
- Service Worker 向浏览器交付
Response,iframe 渲染结果。
可以把它理解为:浏览器仍在请求页面,但处理请求的 Python 应用也运行在浏览器里。
为什么需要会话前缀
同一站点的多个标签页会共享 Service Worker,但不同标签页可能加载不同的数据库、插件和 Datasette 版本。
如果所有请求都交给同一个应用实例,各标签页的配置就会混在一起。为此,每个顶层页面生成随机会话 ID,并启动独立的 Web Worker。Service Worker 根据 /app/<session>/ 前缀,将请求送往相应实例。
为什么不直接在 Service Worker 中运行 Pyodide
Service Worker 的生命周期不适合长期保存应用状态。浏览器可能在较短时间后终止它,具体行为取决于浏览器实现。
因此,这套架构将请求拦截交给 Service Worker,将持续运行的 Python 环境、应用实例和数据库状态放在 Web Worker 中。
用于缺陷复现和 SQLite 版本对比
版本可配置,是这套方案对开发工作尤其有用的部分。
例如,同一组数据和分页参数可以分别加载 Datasette 1.0a42 与 1.0a43:前者用于展示点击下一页后第二页为空的问题,后者展示修复后的行为。复现环境不再只是一段操作说明,而是可以直接打开的应用实例。
SQLite 版本也能通过 sqlite 参数选择。其实现方式是下载对应版本的 WebAssembly Python wheel,安装进 Pyodide,再配置 Datasette 使用它。
配套的 pysqlite3-wasm-wheels 项目提供了多个 SQLite 版本的构建产物,另有工具可在所选版本上执行同一条 SQL 并比较结果。这类能力可用于调查版本间的行为差异,而不必先在本机配置多套 SQLite 环境。
能否推广到其他 Python 应用
这套请求转发机制并不依赖 Datasette 独有的功能,因此也为其他 Python 应用提供了一种浏览器预览环境的实现思路:将运行环境、数据和配置编码进 URL,用于功能演示或问题复现。
不过,迁移仍有边界。依赖 C 或 Rust 扩展的应用,需要具备 Pyodide 兼容的 WebAssembly 构建;SQLite 可以在浏览器内运行,而 PostgreSQL、MySQL 等数据库的浏览器运行方案仍不如 SQLite 成熟。
这项实践的关键不只是“浏览器能执行 Python”,而是通过请求拦截、会话路由和独立执行环境,让原本面向服务器的应用保留更完整的页面与资源加载行为。
