PyScript 无法直接导入官方 `neo4j` 包，因其依赖 C 扩展和底层网络栈（如 `socket`、`ssl`），不兼容 WebAssembly 运行时；本文详解原因、验证方法，并提供可行的纯前端 Neo4j 连接方案。
PyScript 基于 Pyodide，在浏览器中通过 WebAssembly 运行 Python，但它仅支持纯 Python（pure-Python）包——即不包含 C 扩展、不调用系统级 API（如原生 socket、threading、subprocess）、且所有依赖均可被静态编译为 WebAssembly 的库。而官方 neo4j 包不符合这一前提：
- ✅ 使用纯 Python 编写部分逻辑
- ❌ 重度依赖 ssl、socket、select 等 CPython 标准库模块（在 Pyodide 中受限或未完全实现）
- ❌ 依赖 packaging、typing-extensions 等间接依赖，部分版本存在兼容性问题
- ❌ 无官方发布的 pyodide 兼容 wheel，也未收录于 Pyodide 官方包索引
因此，当你在 pyscript.toml 中声明 packages = ["neo4j"]，PyScript 会尝试从 PyPI 下载并安装该包，但因缺失底层能力导致初始化卡死（hang）——这并非你的代码错误，而是架构层面的不兼容。
✅ 验证方式：检查包是否被 Pyodide 支持
可访问 Pyodide Packages Search 或运行以下 PyScript 片段快速验证：
<script type="py" terminal>
import micropip
await micropip.install("pyjokes") # ✅ 成功
print("pyjokes loaded")
try:
await micropip.install("neo4j") # ❌ 报错或超时
except Exception as e:
print("neo4j install failed:", e)
</script>实际执行将抛出 ModuleNotFoundError: No module named '_ssl' 或长时间挂起，印证了核心限制。
✅ 替代方案：使用 Neo4j Browser Driver 的 JavaScript 版本（推荐）
由于 PyScript 本质是“Python on WebAssembly”，它完全支持与 JavaScript 互操作。因此最佳实践是：
- 弃用 Python 驱动，改用官方维护的 neo4j-driver（JavaScript/TypeScript）
- 通过 js. 模块在 PyScript 中调用 JS 驱动，实现无缝协同
示例：在网页中连接 Neo4j 并执行简单查询
<!-- index.html -->
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1.0">
<link rel="stylesheet" href="https://pyscript.net/releases/2024.1.1/core.css">
<script type="module" src="https://pyscript.net/releases/2024.1.1/core.js"></script>
<!-- 引入 Neo4j JS Driver -->
<script type="module">
import { driver } from 'https://cdn.jsdelivr.net/npm/neo4j-driver@5/lib/browser/index.js';
window.neo4jDriver = driver; // 挂载到全局供 PyScript 调用
</script>
</head>
<body>
<div id="output"></div>
<script type="py" terminal>
import js
from pyodide.ffi import to_js
# 配置连接参数（⚠️ 生产环境请勿硬编码凭据！）
uri = "neo4j://your-server:7687"
user = "neo4j"
password = "your-password"
try:
# 初始化驱动（JS 端）
driver = js.neo4jDriver(uri, js.auth.basic(user, password))
session = driver.session()
# 执行 Cypher 查询
result = await session.run("RETURN 'Hello from Neo4j via PyScript!' AS message")
record = await result.single()
message = record.get("message")
# 输出到页面
js.document.getElementById("output").innerText = message
print(f"✅ Success: {message}")
except Exception as e:
error_msg = str(e)
js.document.getElementById("output").innerText = f"❌ Error: {error_msg}"
print("Connection failed:", error_msg)
finally:
if 'session' in locals():
await session.close()
if 'driver' in locals():
await driver.close()
</script>
</body>
</html>? 安全提醒：浏览器端直连 Neo4j 数据库需开放 neo4j:// 或 bolt:// 端口（通常 7687），强烈建议仅用于开发/测试环境。生产部署应通过后端 API 代理请求，避免暴露数据库凭证与内网地址。
✅ 总结与建议
| 方案 | 可行性 | 适用场景 | 备注 |
|---|---|---|---|
| import neo4j（官方包） | ❌ 不可行 | — | 架构不兼容，Pyodide 无法加载 |
| micropip.install("neo4j") | ❌ 失败 | 快速验证 | 会触发 ImportError 或 hang |
| JS Driver + PyScript 互操作 | ✅ 推荐 | 开发/演示/原型 | 利用 PyScript 的 js. 模块桥接，功能完整、性能良好 |
| 自建纯 Python 驱动（如 neo4j-rest-client） | ⚠️ 极不推荐 | — | 已废弃、无维护、不支持 Bolt 协议、存在严重安全风险 |
如需长期支持，可关注 Pyodide 官方 Neo4j 兼容性议题 或向 PyScript GitHub 提交 issue 推动社区适配。但在当前生态下，拥抱 JS 生态 + Python 逻辑胶水，才是 Web 前端集成 Neo4j 的务实之道。
