PyScript通过本地whl安装geopandas后无法导入如何解决

核心错误原因 #

问题本质来自三点：

1. PyScript底层基于Pyodide运行，是WASM编译的Python环境，和普通桌面端CPython的二进制包不兼容，常规渠道下载的桌面端whl（尤其是带C扩展的依赖包）无法在WASM环境加载。
2. geopandas不是纯Python包，依赖shapely、fiona、pyproj、rtree等一整套地理空间底层库，只配置geopandas本身的whl、不安装对应WASM版本的依赖链，必然触发模块找不到报错。
3. 最开始直接在<py-env>写- geopandas安装失败，是因为默认Pyodide源没有默认集成全量地理空间依赖，直接拉取会因缺包中断安装。

可落地方案 #

方案一：在线安装适配版本依赖（最简便） #

直接在<py-env>中按顺序配置所有适配WASM环境的依赖，不需要手动下载whl：

<py-env>
  - folium
  - shapely
  - pyproj
  - fiona
  - geopandas
</py-env>

注意：必须使用和当前Pyodide Python版本匹配的包，从报错信息看你的环境是Python3.10，对应PyScript建议选2022年之后发布的稳定版本，不要用过旧版本。
等<py-env>依赖全部加载完成后，直接在<py-script>块导入即可：

<py-script>
import folium
import json
import geopandas as gpd

m = folium.Map(location=[45, 7], tiles='stamentoner')
m
</py-script>

方案二：本地whl离线部署（适配你当前XAMPP本地环境） #

如果需要完全离线部署，按以下步骤操作：

• 准备适配包：不要下载常规渠道带cp310-win_amd64、cp310-manylinux这类标识的whl，必须找文件名带emscripten、wasm32标识的WASM编译版本，且Python版本号和你当前Pyodide内置版本（3.10）完全匹配，覆盖geopandas全依赖链：shapely、pyproj、fiona、rtree、geopandas。
• 路径校验：把所有whl放到XAMPP站点目录下的wheels文件夹，直接在浏览器访问对应whl地址（比如http://localhost/wheels/geopandas-0.10.2-py2.py3-none-any.whl），确认能正常下载、无404报错。
• 正确配置<py-env>，按底层依赖到上层包的顺序填写本地路径：

<py-env>
  - folium
  - './wheels/shapely-对应版本-cp310-cp310-emscripten_xxx_wasm32.whl'
  - './wheels/pyproj-对应版本-cp310-cp310-emscripten_xxx_wasm32.whl'
  - './wheels/fiona-对应版本-cp310-cp310-emscripten_xxx_wasm32.whl'
  - './wheels/rtree-对应版本-cp310-cp310-emscripten_xxx_wasm32.whl'
  - './wheels/geopandas-0.10.2-py2.py3-none-any.whl'
</py-env>

• 打开Chrome开发者工具的Network面板，刷新页面确认所有whl文件都返回200状态码，没有加载失败，之后再执行导入代码即可。

避坑提示 #

• 绝对不要用file://协议直接打开本地html文件测试，必须用本地HTTP服务（你当前用XAMPP的方式是正确的），否则本地whl会因为跨域/权限问题加载失败。
• 如果导入时仍提示缺模块，直接看报错信息里缺失的模块名，把对应模块的WASM版本whl补到<py-env>配置里即可，geopandas依赖链较长，漏装任意一个包都会触发模块找不到错误。
• 不要尝试在PyScript里用pip安装常规PyPI包，二进制不兼容的问题无法通过pip安装解决。

内容的提问来源于stack exchange，提问作者Aittam93