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 片段快速验证：
实际执行将抛出 ModuleNotFoundError: No module named '_ssl' 或长时间挂起，印证了核心限制。
✅ 替代方案：使用 Neo4j Browser Driver 的 JavaScript 版本（推荐）
由于 PyScript 本质是“Python on WebAssembly”，它完全支持与 JavaScript 互操作。因此最佳实践是：
- 弃用 Python 驱动，改用官方维护的 neo4j-driver（JavaScript/TypeScript）
- 通过 js. 模块在 PyScript 中调用 JS 驱动，实现无缝协同
示例：在网页中连接 Neo4j 并执行简单查询
? 安全提醒：浏览器端直连 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 的务实之道。
