解决Cartopy安装失败：从GEOS/Proj依赖到跨平台环境搭建

1. 问题定位：为什么Cartopy的“Wheel”构建会失败？

如果你在Python地理数据可视化的路上，正兴致勃勃地准备用pip install cartopy大展拳脚，却迎面撞上“Getting requirements to build wheel did not run successfully.”这行冰冷的报错，别慌，你绝不是一个人。这个错误堪称Python科学计算库安装路上的“经典拦路虎”，尤其对于像Cartopy这样依赖复杂C/C++扩展和系统库的“重量级选手”来说。

简单来说，这个报错是pip在尝试为Cartopy构建“wheel”安装包时，在准备构建环境（即收集和安装构建依赖）这一步就失败了。Wheel是Python的一种预编译二进制分发格式，理想情况下，pip应该直接从PyPI（Python包索引）下载一个针对你操作系统和Python版本的、现成的wheel文件，解压即用，无需本地编译。但Cartopy的官方PyPI页面并不总是为所有平台提供预编译的wheel，特别是对于Windows和某些Linux发行版的新版本或特定架构。当没有现成的wheel时，pip就会退而求其次，尝试从源代码（sdist）构建，这个过程就需要你的系统具备完整的编译工具链和所有必要的底层库。

所以，这个错误的本质是：你的系统缺少Cartopy从源代码构建所必需的前置条件。它可能包括C++编译器（如MSVC或gcc）、GEOS和Proj这两个地理空间库的开发头文件、以及Python的开发头文件等。错误信息本身很笼统，它只是告诉你“准备构建wheel的依赖没搞定”，但具体是哪个依赖、哪里出了问题，需要你像侦探一样层层排查。

2. 核心依赖拆解：Cartopy到底需要什么？

要解决构建问题，我们必须先理解Cartopy的“地基”是什么。Cartopy本身是一个Python库，但它严重依赖两个用C/C++编写的地理空间数据处理“引擎”：GEOS和Proj。

• GEOS： 全称Geometry Engine - Open Source。它是JTS（Java Topology Suite）的C++移植版，负责处理所有的几何图形运算，比如判断两个多边形是否相交、计算缓冲区、进行空间关系判断等。没有GEOS，Cartopy就无法进行任何核心的空间分析。
• Proj： 这是一个功能强大的坐标转换库。地球不是平的，我们需要在不同的地图投影（比如墨卡托投影、兰伯特投影）和地理坐标系（比如WGS84）之间进行转换。Cartopy绘制地图、将数据定位到正确位置，全靠Proj在背后进行复杂的数学计算。

在Linux或macOS上，这两个库通常可以通过系统包管理器（如apt,yum,brew）轻松安装。但pip install只会处理Python层面的依赖，它不会、也无法替你安装这些系统级的C/C++库。在Windows上，情况更复杂，因为缺少统一的包管理器，通常需要预编译的二进制文件或借助第三方发行版。

因此，安装Cartopy的正确姿势，永远不是直接pip install cartopy，而是先确保GEOS和Proj已正确安装并配置好，然后再通过pip安装Cartopy的Python绑定部分。忽视这个顺序，就会直接触发我们遇到的这个构建错误。

3. 分平台实战：搭建稳固的构建环境

不同操作系统的软件生态差异巨大，因此解决方案也必须“因地制宜”。下面我们针对Windows、macOS和Linux三大平台，给出最直接有效的环境准备方案。

3.1 Windows平台：拥抱“全家桶”解决方案

对于Windows用户，最省心、成功率最高的方法，就是绕过从源代码构建的“坑”，直接使用预编译好的二进制发行版。我强烈推荐以下两种方案：

方案一：使用conda（Anaconda/Miniconda）conda是一个跨平台的包和环境管理器，它的核心优势在于能同时管理Python包和非Python的二进制依赖（如GEOS、Proj的Windows版本）。

1. 安装Miniconda： 如果你不需要Anaconda附带的大量科学计算包，可以安装更轻量的Miniconda。从官网下载对应Python 3.x的Windows 64位安装程序。
2. 创建并激活新环境（可选但推荐）： 这能避免污染你的基础Python环境。

   conda create -n cartopy_env python=3.9 conda activate cartopy_env

   这里指定Python 3.9是因为它通常有最好的兼容性，你也可以选择其他3.7+的版本。
3. 通过conda-forge频道安装： conda-forge是一个社区维护的、包版本通常更新的频道。

   conda install -c conda-forge cartopy

   这一条命令，conda会自动为你解决所有依赖，包括Python、cartopy、GEOS、Proj以及其他必要的库（如Shapely, numpy等）。这是最无痛的方案。

注意： 有些公司的IT策略可能限制了Anaconda的使用。如果遇到网络问题，可以尝试配置conda的国内镜像源（如清华、中科大源），但需注意合规性。

方案二：使用第三方预编译的Wheel文件如果坚持使用原生pip，可以手动寻找为Windows预编译好的Cartopy wheel文件。一个可靠的来源是Christoph Gohlke维护的Unofficial Windows Binaries for Python Extension Packages网站。你需要根据你的Python版本（如3.9）和系统架构（64位）下载对应的.whl文件，例如Cartopy‑0.20.2‑cp39‑cp39‑win_amd64.whl。

下载后，在命令行进入该文件所在目录，使用pip安装：

pip install Cartopy‑0.20.2‑cp39‑cp39‑win_amd64.whl

这种方式同样避免了本地编译。但缺点是，你需要手动匹配版本，且可能找不到最新的Cartopy版本。

3.2 macOS平台：倚仗Homebrew的威力

macOS用户拥有强大的第三方包管理器Homebrew，它能极大地简化系统级依赖的安装。

1. 安装Homebrew： 如果你还没有安装，请访问brew.sh获取安装命令。
2. 安装GEOS和Proj： 打开终端，执行以下命令。

   brew install geos proj

   Homebrew会自动下载、编译并安装这两个库及其头文件到标准路径（/usr/local/opt/下），pip在后续构建时能够找到它们。
3. 安装Cartopy： 现在，你可以尝试使用pip安装了。但为了确保pip能使用最新版本，建议先升级pip和setuptools。

   pip install --upgrade pip setuptools wheel pip install cartopy

   如果此时仍然报错，可能是Python开发头文件的问题。确保你安装了Xcode Command Line Tools：

   xcode-select --install

3.3 Linux平台：善用系统包管理器

Linux发行版通常自带了完善的开发工具链和软件仓库。以常见的Ubuntu/Debian和CentOS/RHEL为例：

对于Ubuntu/Debian系：

# 1. 更新软件包列表 sudo apt update # 2. 安装编译工具和地理空间库的开发文件 sudo apt install build-essential python3-dev libgeos-dev libproj-dev # 3. 使用pip安装Cartopy pip install cartopy --user # 如果只想为当前用户安装，使用--user # 或 pip install cartopy # 在虚拟环境中使用

对于CentOS/RHEL/Fedora系：

# 1. 安装开发工具组和EPEL仓库（CentOS/RHEL需要） sudo yum groupinstall "Development Tools" sudo yum install epel-release # 对于CentOS/RHEL # 2. 安装地理空间库的开发文件 # CentOS/RHEL 7/8: sudo yum install geos-devel proj-devel python3-devel # Fedora: sudo dnf install geos-devel proj-devel python3-devel # 3. 使用pip安装 pip install cartopy

关键就在于libgeos-dev和libproj-dev（或geos-devel,proj-devel）这两个包。它们提供了编译Cartopy C++扩展所必须的头文件（.h）和链接库（.so/.a）。只安装libgeos和libproj是不够的，那只是运行时库。

4. 通用排查与深度修复指南

即使按照上述平台指南操作，有时仍会遇到问题。下面是一些通用的高级排查和修复技巧。

4.1 解读错误日志：找到真正的“元凶”

pip的报错信息只是冰山一角。要看到完整的错误堆栈，需要在安装命令后添加-v（verbose）参数，或者将错误输出重定向到文件仔细查看。

pip install cartopy -v 2>&1 | tee install_log.txt

打开install_log.txt，搜索关键词如“error:”、“fatal error:”、“not found”、“cannot find”。常见的致命信息包括：

• geos_c.h: No such file or directory->GEOS的头文件没找到。
• proj.h: No such file or directory->Proj的头文件没找到。
• error: command 'gcc' failed->编译器本身有问题或缺少必要的编译标志。

这些信息会明确指出缺失的具体组件。

4.2 手动指定依赖库路径

有时，即使库已安装，pip的构建过程也可能找不到它们，尤其是当你将库安装在了非标准路径（比如自定义编译安装的GEOS/Proj）。这时，你需要通过环境变量告知构建系统。

在安装前，临时设置这些环境变量（以bash为例）：

# 假设你的GEOS安装在 /usr/local/geos， Proj安装在 /usr/local/proj export GEOS_DIR=/usr/local/geos export PROJ_DIR=/usr/local/proj export CPLUS_INCLUDE_PATH="$GEOS_DIR/include:$PROJ_DIR/include:$CPLUS_INCLUDE_PATH" export LIBRARY_PATH="$GEOS_DIR/lib:$PROJ_DIR/lib:$LIBRARY_PATH" export LD_LIBRARY_PATH="$GEOS_DIR/lib:$PROJ_DIR/lib:$LD_LIBRARY_PATH" # Linux # 对于macOS，可能是DYLD_LIBRARY_PATH pip install cartopy

对于Windows，你需要在系统属性或命令行中设置类似的INCLUDE和LIB环境变量，指向包含.h和.lib文件的目录。

4.3 使用pyproject.toml感知的构建后端

现代Python打包工具（如setuptools,pip) 越来越依赖pyproject.toml文件来声明构建依赖。Cartopy的新版本应该包含了这个文件。确保你的pip和setuptools是最新的，它们能更好地处理这类构建。

pip install --upgrade pip setuptools wheel

升级后再次尝试安装，有时能解决因构建后端过旧导致的兼容性问题。

4.4 终极备选：从GitHub源码安装

如果所有方法都失败了，你可以尝试直接从Cartopy的GitHub仓库安装开发版。这通常需要更完整的开发环境，但有时能绕过PyPI上源码包的一些历史问题。

# 1. 确保已安装git # 2. 克隆仓库（或下载源码zip） git clone https://github.com/SciTools/cartopy.git cd cartopy # 3. 在源码目录中安装 pip install -e . # “-e”代表可编辑模式，方便开发 # 或 pip install .

从源码安装会强制触发完整的构建流程，结合-v参数，你能获得最详细的错误信息用于诊断。

5. 安装验证与后续步骤

安装成功后，不要急于开始画图，先进行一个简单的验证，确保Cartopy及其核心依赖都正常工作。

打开Python解释器或创建一个测试脚本：

import cartopy import cartopy.crs as ccrs import matplotlib.pyplot as plt print(f"Cartopy version: {cartopy.__version__}") # 尝试创建一个最简单的地图 fig = plt.figure(figsize=(10, 5)) ax = fig.add_subplot(1, 1, 1, projection=ccrs.PlateCarree()) ax.coastlines() # 绘制海岸线 ax.gridlines(draw_labels=True) # 添加网格和标签 plt.title("Cartopy 安装验证 - 全球海岸线") plt.show()

如果这段代码能成功运行并弹出一个带有全球海岸线的地图窗口，那么恭喜你，Cartopy已经准备就绪。

如果import cartopy时出现类似libgeos_c.so.1: cannot open shared object file的错误，这属于运行时链接错误，说明系统找不到GEOS的动态链接库。解决方法与构建时类似：确保LD_LIBRARY_PATH（Linux）或DYLD_LIBRARY_PATH（macOS）环境变量包含了GEOS/Proj库的路径，或者将库文件链接到系统标准库路径下。

6. 避坑心得与经验之谈

踩过无数次坑后，我总结出几条血泪经验，希望能帮你少走弯路：

1. 虚拟环境是必需品： 无论是venv、virtualenv还是conda env，务必在虚拟环境中安装像Cartopy这样的复杂库。这能完美隔离依赖，避免破坏系统Python环境，也便于管理和清理。项目一个环境，是最佳实践。
2. Windows用户首选Conda： 在Windows上，与系统库和编译器斗争的成本极高。除非有特殊原因，否则强烈建议Windows用户直接使用conda安装Cartopy。这是性价比最高的选择，省下的时间足够你学习更多Cartopy的用法。
3. 关注版本兼容性矩阵： Cartopy、GEOS、Proj、Matplotlib乃至NumPy之间都存在版本依赖。在升级任何一方时，都要留意官方文档或发布说明中的兼容性提示。例如，Cartopy 0.20+可能需要Proj 6.x或更高版本。
4. 理解“开发包”与“运行时包”的区别： 这是Linux/macOS用户最常见的困惑。apt-get install libgeos-dev安装的是开发包（含头文件），用于编译。而libgeos是运行时包，只包含共享库。安装时务必确认你装的是-dev或-devel版本。
5. 善用搜索引擎，但甄别信息时效性： 你遇到的问题很可能别人也遇到过。搜索错误信息时，加上你的操作系统和Python版本关键词。但要注意，很多中文博客的解决方案可能已经过时（比如针对Cartopy 0.16，而你现在装的是0.21）。优先查看Stack Overflow上的高票答案和项目官方GitHub的Issue页面。

最后，记住这个安装哲学：对于依赖复杂原生库的Python包，安装的核心从来不是pip install那一步，而是之前系统级依赖的妥善准备。把GEOS和Proj这两个“地基”打牢，Cartopy这座“高楼”才能稳稳立住。当你成功跨过安装这道坎，你会发现Cartopy带来的强大地理可视化能力，绝对值得这番折腾。