正在加载 Python 运行时...
``` 然后启动一个本地 HTTP 服务： ```bash python3 -m http.server 8000 ``` 打开： ```text http://localhost:8000 ``` 点击按钮后，页面会显示 `计算结果：668`。 根据 [Pyodide 官方快速入门](https://pyodide.org/en/stable/usage/quickstart.html)，`pyodide.js` 提供异步的 `loadPyodide()`，它会初始化 Python 环境；`runPython()` 接收 Python 源码字符串，并把可转换的结果返回给 JavaScript。 这已经是一个真实的 Wasm 浏览器应用：页面加载 Pyodide 的 WebAssembly 运行时，Python 负责计算，JavaScript 负责加载、事件和 DOM 展示。 ## 做成一个实用的浏览器小工具 把 Python 代码直接嵌在 JavaScript 字符串中适合最小演示。项目稍大后，最好把 Python 和页面代码分开。 目录结构如下： ```text python-wasm-demo/ ├── index.html └── main.py ``` 创建 `main.py`，实现一个简单文本分析器： ```python import json import re from collections import Counter def analyze_text(text: str) -> str: """分析文本，并返回便于 JavaScript 使用的 JSON 字符串。""" lines = text.splitlines() ascii_words = re.findall(r"[A-Za-z0-9_]+", text.lower()) frequencies = Counter(ascii_words).most_common(5) result = { "characters": len(text), "characters_without_spaces": sum( 1 for character in text if not character.isspace() ), "lines": len(lines), "ascii_words": len(ascii_words), "top_ascii_words": frequencies, } return json.dumps(result, ensure_ascii=False) ``` 再把 `index.html` 改成一个完整交互页面： ```html正在加载 Python 运行时...
等待运行``` 再次运行本地服务并打开页面： ```bash python3 -m http.server 8000 ``` 用户输入文本后，执行链路如下： ```text 用户点击按钮 ↓ JavaScript 读取 textarea ↓ 字符串写入 Pyodide 全局变量 ↓ Wasm 中的 Python 运行时调用 analyze_text ↓ Python 返回 JSON 字符串 ↓ JavaScript 解析结果并更新 pre 元素 ``` 这个例子故意使用 JSON 字符串作为 Python 与 JavaScript 的边界。简单字符串、数字和布尔值转换直接；复杂 Python 对象可能以代理对象形式暴露，需要理解转换和释放规则。明确的 JSON 契约更容易调试，也适合作为前后两种语言之间的稳定接口。 ## 为什么要通过 HTTP 服务打开 直接双击 `index.html`，地址会是 `file://`。浏览器对本地文件读取有限制，`fetch("./main.py")` 很可能失败。 使用 `python3 -m http.server` 后，页面和 `main.py` 通过 `http://localhost:8000` 提供，浏览器会按正常 Web 资源处理它们。 上线时也要正确配置静态资源路径、缓存和跨域策略。Pyodide 官方 FAQ 同样提醒，本地文件与跨域请求会受到浏览器同源策略约束。 ## 如何加载 Python 第三方包 Pyodide 初始化完成后，默认提供 Python 标准库。其他包需要额外加载。 如果包已经包含在 Pyodide 分发中，可以从 JavaScript 加载： ```javascript await pyodide.loadPackage("numpy"); const result = pyodide.runPython(` import numpy as np values = np.array([1, 2, 3, 4]) float(values.mean()) `); console.log(result); ``` 对于纯 Python wheel 或 Pyodide 兼容包，通常使用 `micropip`： ```javascript await pyodide.loadPackage("micropip"); const micropip = pyodide.pyimport("micropip"); await micropip.install("snowballstemmer"); ``` [Pyodide 加载包文档](https://pyodide.org/en/stable/usage/loading-packages.html)指出，纯 Python wheel 通常更容易使用；带有 C、Rust 等本机扩展的包必须有兼容的 `wasm32/emscripten` 构建，不能认为所有能被桌面版 `pip` 安装的包都能在浏览器工作。 每增加一个包，还会增加下载体积和初始化时间。实际产品应只加载当前页面真正需要的依赖，并配置长期缓存。 ## 耗时计算要放进 Web Worker 最小示例在浏览器主线程运行 Python。短计算没有问题，但耗时任务会阻塞按钮、滚动和动画，让页面看起来“卡死”。 生产应用应把长时间 Python 计算移到 Web Worker： ```text 主线程：界面、点击、进度、结果展示 ↕ postMessage Worker：加载 Pyodide、执行 Python、返回结果 ``` 当前 Pyodide 官方文档要求使用模块类型 Worker，因为它依赖 ES 模块形式的运行文件。创建方式类似： ```javascript const worker = new Worker("./worker.js", { type: "module" }); worker.postMessage({ id: "task-1", text: "需要分析的文本", }); worker.addEventListener("message", (event) => { console.log(event.data); }); ``` Worker 不能直接操作 DOM，只能通过消息与主线程交换数据。这反而能形成更清楚的边界：Worker 负责计算，主线程负责界面。 完整模式可参考 [Pyodide Web Worker 官方文档](https://pyodide.org/en/stable/usage/webworker.html)。 ## 浏览器接入 Wasm 的通用方式 如果使用 Rust 或 C 编译出独立的 `math.wasm`，不经过 Pyodide，浏览器通常通过 JavaScript 原生 API 加载： ```javascript const { instance } = await WebAssembly.instantiateStreaming( fetch("./math.wasm"), {} ); const result = instance.exports.add(20, 22); console.log(result); ``` 这个例子展示了 Wasm 接入浏览器的核心结构： - `fetch()` 下载二进制模块； - `instantiateStreaming()` 边接收边编译并实例化； - 第二个参数提供模块需要的导入对象； - `instance.exports` 暴露模块导出的函数、内存等能力。 服务器还应为 `.wasm` 返回正确的 `Content-Type: application/wasm`，否则流式实例化可能失败。工具链通常会生成一层 JavaScript 胶水代码，帮助处理字符串、数组、内存和异步接口。 Pyodide 把这些底层加载和语言运行时细节封装在 `loadPyodide()` 后面，所以 Python 示例看起来更像日常 Web 开发。 ## 从 Demo 走向产品要注意什么 ### 控制首屏成本 Python 运行时和科学计算包可能比普通前端脚本大得多。不要在用户还没进入相关功能时就全部加载。 可以采用： - 用户进入工具页后再懒加载； - 显示真实的初始化状态； - 使用固定版本和长期缓存； - 只加载需要的包； - 对常用资源使用 CDN 或自行托管。 ### 固定依赖版本 演示中使用了明确版本 `v314.0.4`。生产环境不要使用 `dev` 或不固定版本的地址，否则上游更新可能造成行为改变、缓存失效或兼容问题。 升级时应测试 Python 版本、包 ABI、浏览器支持和产物大小，而不是只替换 CDN URL。 ### 减少跨边界调用 JavaScript 与 Python/Wasm 可以互相调用，但频繁传递大量对象可能抵消计算收益。 更好的方式是一次传入一批数据，在 Wasm 内完成一段完整计算，再一次返回结构化结果。把循环放在 Wasm 内部，通常比让 JavaScript 每次循环都跨边界调用更合理。 ### 不要把浏览器当完整操作系统 桌面 Python 程序常依赖文件系统、子进程、原始 Socket、系统线程或本机动态库。浏览器环境不会原样提供这些能力。 网络访问要遵守 Fetch 和 CORS；文件访问要经过用户选择或浏览器 API；不兼容的本机扩展需要专门移植。评估项目时，应先列出依赖的系统能力，再判断能否在浏览器中替代。 ### 不要运行不受信任的无限代码 Wasm 有内存安全和沙箱边界，但用户提交的 Python 仍可能死循环、占满 CPU 或申请大量内存。在线代码执行器需要 Worker 隔离、超时、中止机制、资源限制和输入校验。 沙箱解决的是能力边界，不自动解决拒绝服务和业务滥用。 ## 常见误解 **Wasm 一定比 JavaScript 快**：不一定。算法、运行时、数据交换和启动成本都会影响结果，必须用真实负载测试。 **Wasm 可以直接操作 DOM**：通常需要通过 JavaScript 或宿主提供的接口。Wasm 本身不内置 DOM。 **Python 文件被直接编译成了小型 wasm**：本文的 Pyodide 路线是由 Wasm 版 CPython 执行 Python 代码，业务脚本并不是独立 Wasm 模块。 **所有 Python 包都能在 Pyodide 安装**：纯 Python 包通常更容易；本机扩展必须有兼容的 Emscripten/Wasm 构建。 **有沙箱就不用考虑安全**：错误暴露的宿主接口、资源耗尽和供应链风险仍然存在。 **打开本地 HTML 就能工作**：页面通过 `fetch()` 加载 Python 或 Wasm 文件时，应使用本地 HTTP 服务，避免 `file://` 限制。 ## 如何判断项目是否值得用 Wasm 在引入 Wasm 前，可以回答五个问题： 1. 是否有必须复用的非 JavaScript 代码或生态？ 2. 性能瓶颈是否真的是 CPU 计算，而不是网络或 DOM？ 3. 计算是否足够大，能覆盖运行时启动和语言边界成本？ 4. 所需依赖是否支持浏览器 Wasm 环境？ 5. 团队是否能维护构建、调试、缓存和升级链路？ 如果只是几十行普通页面逻辑，JavaScript 往往更直接。如果要把成熟算法库、Python 数据能力或重型计算带到浏览器，Wasm 才开始显示真正价值。 ## 总结 Wasm 是一种安全、紧凑、可移植的二进制执行格式，也是多种语言进入浏览器和其他运行时的共同编译目标。它最重要的作用不是取代 JavaScript，而是扩展 Web 能执行的语言、库和计算类型。 用 Python 快速体验 Wasm，最合适的入门方式之一是 Pyodide： 1. 浏览器加载 Wasm 版 CPython； 2. JavaScript 用 `runPython()` 或 `runPythonAsync()` 执行 Python； 3. 两种语言通过明确的数据接口交换输入输出； 4. 页面仍由 JavaScript 管理； 5. 重计算放进 Web Worker，避免阻塞界面。 当你能清楚区分“Wasm 运行时”“Python 业务代码”和“JavaScript 宿主”这三层，就已经掌握了把 Python Wasm 应用到浏览器的基本架构。 ## 参考资料 - [WebAssembly 官方网站](https://webassembly.org/) - [WebAssembly Specifications](https://webassembly.org/specs/) - [WebAssembly Developers Guide](https://webassembly.org/getting-started/developers-guide/) - [Pyodide 官方快速入门](https://pyodide.org/en/stable/usage/quickstart.html) - [Pyodide 加载第三方包](https://pyodide.org/en/stable/usage/loading-packages.html) - [Pyodide Web Worker](https://pyodide.org/en/stable/usage/webworker.html)