第二章：安装与环境配置
2.1 系统要求
在安装 GeoPipeAgent 之前，请确认你的环境满足以下要求：
| 要求 | 最低版本 | 推荐版本 |
|---|---|---|
| Python | 3.10 | 3.11+ |
| pip | 21.0 | 最新版 |
| 操作系统 | Windows / macOS / Linux | Ubuntu 22.04+ / macOS 13+ |
2.2 安装方式
GeoPipeAgent 通过 pip 安装，支持基础安装和带可选依赖的扩展安装。
2.2.1 从源码安装（推荐）
# 克隆仓库
git clone https://github.com/znlgis/GeoPipeAgent.git
cd GeoPipeAgent# 基础安装（仅核心功能：IO、矢量、栅格步骤）
pip install -e .# 安装全部可选依赖（推荐开发者使用）
pip install -e ".[dev,analysis,network]"
2.2.2 可选依赖组说明
GeoPipeAgent 将可选依赖划分为三个组，按需安装：
| 依赖组 | 包含的包 | 启用的功能 |
|---|---|---|
dev |
pytest, pytest-cov | 开发与测试工具 |
analysis |
scipy, scikit-learn, matplotlib | 空间分析步骤（泰森多边形、热力图、插值、聚类） |
network |
networkx, geopy | 网络分析步骤（最短路径、服务区、地理编码） |
# 仅安装空间分析依赖
pip install -e ".[analysis]"# 仅安装网络分析依赖
pip install -e ".[network]"# 同时安装空间分析和网络分析
pip install -e ".[analysis,network]"
2.3 核心依赖说明
基础安装会自动安装以下核心依赖（已在 pyproject.toml 中定义）：
| 依赖包 | 版本要求 | 用途 |
|---|---|---|
click |
>=8.0 | CLI 命令行接口框架 |
pyyaml |
>=6.0 | YAML 流水线解析 |
numpy |
>=1.24 | 数值计算（栅格分析依赖） |
geopandas |
>=0.14 | 矢量数据处理引擎 |
shapely |
>=2.0 | 几何运算库 |
pyproj |
>=3.5 | 坐标参考系转换 |
rasterio |
>=1.3 | 栅格数据读写 |
注意：
geopandas本身依赖fiona（或pyogrio）、pyproj、shapely，这些会随 geopandas 自动安装。
2.4 验证安装
安装完成后，运行以下命令验证：
# 查看版本
geopipe-agent --version# 列出所有内置步骤（应显示 33 个步骤）
geopipe-agent list-steps# 查看可用后端（显示各后端的可用状态）
geopipe-agent backends
预期输出示例：
# geopipe-agent list-steps
ID Name Category Backends
--------------------------------------------------------------------------------
io.read_vector 读取矢量数据 io -
io.write_vector 写入矢量数据 io -
io.read_raster 读取栅格数据 io -
io.write_raster 写入栅格数据 io -
vector.buffer 矢量缓冲区分析 vector native_python, qgis_process
vector.clip 矢量裁剪 vector native_python, qgis_process
...Total: 33 steps
// geopipe-agent backends
[{"name": "native_python", "available": true},{"name": "gdal_cli", "available": false},{"name": "gdal_python", "available": false},{"name": "qgis_process", "available": false},{"name": "pyqgis", "available": false},{"name": "generic_cli", "available": true},{"name": "curl_api", "available": true}
]
2.5 推荐使用虚拟环境
强烈建议在虚拟环境中安装，避免与系统包产生冲突：
# 使用 venv（标准库）
python -m venv geopipe-env
source geopipe-env/bin/activate # Linux / macOS
geopipe-env\Scripts\activate.bat # Windows# 在激活的虚拟环境中安装
pip install -e ".[dev,analysis,network]"
或使用 conda：
# 创建 conda 环境（geopandas 在 conda-forge 上依赖更完整）
conda create -n geopipe python=3.11
conda activate geopipe
conda install -c conda-forge geopandas rasterio pyproj shapely
pip install -e ".[dev,analysis,network]"
提示：在 Windows 上，推荐使用 conda 安装 geopandas，避免 GDAL/Fiona 的编译问题。在 Linux/macOS 上，pip 直接安装通常无问题。
2.6 安装外部后端工具（可选）
基础安装只需 Python 环境即可使用 native_python 后端。如需使用其他后端，需要额外安装：
GDAL CLI 后端（gdal_cli）
# Ubuntu
sudo apt-get install gdal-bin# macOS (Homebrew)
brew install gdal# 验证
ogr2ogr --version
GDAL Python 后端（gdal_python）
# Ubuntu
sudo apt-get install python3-gdal# 或通过 pip（需要先安装系统 GDAL）
pip install GDAL==$(gdal-config --version)
QGIS 后端（qgis_process / pyqgis）
参考 QGIS 官方安装指南安装 QGIS Desktop，安装后 qgis_process 命令行工具会自动注册到系统 PATH。
2.7 开发环境配置
如果你计划为 GeoPipeAgent 贡献代码或开发自定义步骤，需要安装开发依赖：
# 安装包括测试工具在内的所有依赖
pip install -e ".[dev,analysis,network]"# 运行完整测试套件
python -m pytest -v# 运行带覆盖率的测试
python -m pytest -v --cov=geopipe_agent --cov-report=term-missing
2.8 常见安装问题
问题 1：shapely 版本冲突
GeoPipeAgent 要求 shapely>=2.0。如果系统中安装了旧版 shapely，升级：
pip install --upgrade "shapely>=2.0"
问题 2：geopandas 安装失败（Windows）
Windows 上 geopandas 可能因 GDAL/Fiona 编译失败。推荐方案：
# 方案一：使用 conda-forge
conda install -c conda-forge geopandas# 方案二：使用预编译的 wheel（从 Christoph Gohlke 的网站）
pip install pipwin
pipwin install gdal fiona geopandas
问题 3：rasterio 安装失败
类似 geopandas，rasterio 在 Windows 上建议使用 conda：
conda install -c conda-forge rasterio
问题 4：geopipe-agent 命令找不到
这通常是因为 Python scripts 目录不在 PATH 中。解决方案：
# 方案一：使用 python -m 方式运行
python -m geopipe_agent.cli --version# 方案二：找到 scripts 目录并加入 PATH
python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
# 将输出的路径加入系统 PATH
问题 5：scipy / scikit-learn 安装慢
空间分析依赖较大，如果 pip 安装较慢，可以使用国内镜像：
pip install -e ".[analysis,network]" -i https://pypi.tuna.tsinghua.edu.cn/simple/
2.9 本章小结
本章介绍了 GeoPipeAgent 的安装与环境配置：
- 系统要求：Python 3.10+，推荐使用虚拟环境
- 安装命令：
pip install -e ".[dev,analysis,network]"安装全部依赖 - 可选依赖组：
analysis（空间分析）和network（网络分析）按需安装 - 安装验证：通过
geopipe-agent list-steps和geopipe-agent backends验证 - 外部后端：GDAL、QGIS 等外部工具按需安装，默认
native_python后端无需额外安装
下一章将编写并运行你的第一个 GeoPipeAgent 流水线。
导航：← 第一章：概述与核心理念 ｜ 第三章：快速上手 →