跳到主要内容

安装

选择正确的 wheel​

正式包名、导入名和 CLI 名称都只有一个：voxelkit。wheel 与 CPython ABI、操作系统和 CPU 架构绑定， 请下载与目标环境完全匹配的文件。

环境文件名示例
macOS Intel / Apple Silicon，CPython 3.9voxelkit-0.10.0-cp39-cp39-macosx_14_0_universal2.whl
Linux x86_64，CPython 3.10voxelkit-0.10.0-cp310-cp310-linux_x86_64.whl

安装本地 wheel：

python3 -m pip install /path/to/voxelkit-0.10.0-<abi>-<platform>.whl

建议在项目虚拟环境中安装：

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install /path/to/voxelkit-0.10.0-<abi>-<platform>.whl

验证​

python3 -c 'from voxelkit import Vfp, compile_json; print("VoxelKit ready")'
voxelkit --help

两条命令均成功后，即可使用同一 SDK 完成读取、提取和编译。

常见安装问题​

  • not a supported wheel：Python 主/次版本、操作系统或 CPU 架构与 wheel 标签不匹配；先执行 python3 --version 和 python3 -c 'import platform; print(platform.platform(), platform.machine())'。
  • ModuleNotFoundError: voxelkit：确认安装命令和运行代码使用的是同一个 Python / 虚拟环境。
  • 从旧版本迁移：voxelkit_compiler 已停止作为新版本分发。安装 0.10.0 后统一改为 from voxelkit import ...。

不要通过源码目录执行生产安装。正式发布 wheel 已将编译实现编译为原生模块；维护仓库源码只用于 SDK 开发与平台构建。