Windows + WSL 上安装和配置 GDAL 的完整踩坑指南

问题背景
核心原因分析
解决方案对比
- 方案对比表
方案一：Windows 上用 Gohlke 预编译 Wheel（最快）
方案二：Windows 上安装 OSGeo4W 提供系统库（进阶）
方案三：WSL (Ubuntu) 上升级系统 GDAL（最推荐）
方案四：Windows 上用 Miniconda（长期项目推荐，不熟悉 WSL）
各方案适用场景
常见坑与排查
总结：选择适合你的「一个方案」
- 实战建议
- 快速命令表
延伸阅读

问题背景

如果你是 GIS 开发者，肯定被 GDAL 坑过。

当你在 Windows 或用 Python 3.13 时，满怀希望地敲下 uv add GDAL，然后你会看到：

× Failed to build gdal==3.12.0.post1
├─▶ The build backend returned an error
╰─▶ Call to setuptools.build_meta.build_wheel failed (exit code: 1)
    ...
    extensions/gdal_wrap.cpp(3464): fatal error C1083: 无法打开包含文件: "cpl_port.h": No such file or directory
    error: command 'cl.exe' failed with exit code 2

或者在 WSL 里折腾了半天，终于装上了 GDAL，但又冒出来这个：

Exception: Python bindings of GDAL 3.11.4 require at least libgdal 3.11.4, but 3.4.1 was found

我之前也被这些问题虐过。这篇文章就是我的「血泪史」总结。

核心原因分析

1. Windows 上的困局

PyPI 上的 GDAL 从 3.9 开始就 没有 Windows wheel 了。这是什么意思？就是说：

💾 Windows 用户想安装 GDAL？没 wheel，你要自己编译源码
📦 源码编译需要 C 头文件（gdal.h、cpl_port.h 等）
🚫 可是你的 Windows 机器上根本没这些文件（需要完整的 GDAL 开发环境，那玩意几百MB）
💥 编译失败，完游

2. Python 版本问题

warning: Resolving despite existing lockfile due to fork markers being disjoint
with requires-python: python_full_version >= '3.13' vs python_full_version == '3.12.*'

这个 warning 说明你的项目声明支持 Python 3.13+，但实际用 3.12。uv 会强制重新解析依赖，导致又回到源码编译的坑。

3. WSL 上的版本不匹配

WSL 上 apt 默认仓库的 GDAL 是 3.4.1（Ubuntu 22.04）或 3.8.4（Ubuntu 24.04），但你的项目要求 3.11.4。编译时系统库版本与 Python wheel 版本不匹配，导致编译失败。

解决方案对比

方案对比表

平台	最佳方案	时间	难度	维护
Windows 裸 Python（快速开发）	Gohlke 预编译 wheel	3 分钟	⭐	简单
Windows（长期项目/不熟悉WSL）	Miniconda + conda-forge	5 分钟	⭐	最简单
Windows + 系统依赖	OSGeo4W	15 分钟	⭐⭐	麻烦
WSL (Ubuntu 22.04/24.04)	升级系统 GDAL + uv	5 分钟	⭐	简单

方案一：Windows 上用 Gohlke 预编译 Wheel（最快）

问题描述

你已经装了 Python 3.12，uv add GDAL 还是失败。

解决步骤

1. 下载预编译 wheel

去 Christoph Gohlke 的官方仓库：

https://github.com/cgohlke/geospatial-wheels/releases

下载对应你的 Python 版本和系统的 wheel：

Python 3.12 + Windows x64: GDAL-3.11.4-cp312-cp312-win_amd64.whl
Python 3.13 + Windows x64: GDAL-3.11.4-cp313-cp313-win_amd64.whl

2. 直接用 uv 安装（支持在线链接）

# 最推荐：不用自己下载，直接在线安装
uv add https://github.com/cgohlke/geospatial-wheels/releases/download/v2025.10.25/GDAL-3.11.4-cp312-cp312-win_amd64.whl

# 或者如果已下载本地，用本地路径
uv add path\to\GDAL-3.11.4-cp312-cp312-win_amd64.whl

3. 验证安装

from osgeo import gdal
print(gdal.__version__)  # 应输出 3.11.4

为什么这个方法最爽

✅ 快得不行：30 秒搞定，真的。还有人能比这更快吗 ✅ 零问题：Wheel 已经预编译好了，没有源码编译的各种诡异错误 ✅ 值得信任：Christoph Gohlke 维护这个库超过 10 年了，这哥们是真的强

其他常用包的 Wheel 列表

在同一个 release 里你还能找到其他 Windows 恶梦包：

# 一键全装（推荐）
uv add https://github.com/cgohlke/geospatial-wheels/releases/download/v2025.10.25/GDAL-3.11.4-cp312-cp312-win_amd64.whl
uv add https://github.com/cgohlke/geospatial-wheels/releases/download/v2025.10.25/Fiona-1.10.1-cp312-cp312-win_amd64.whl
uv add https://github.com/cgohlke/geospatial-wheels/releases/download/v2025.10.25/rasterio-1.4.3-cp312-cp312-win_amd64.whl
uv add https://github.com/cgohlke/geospatial-wheels/releases/download/v2025.10.25/pyproj-3.7.2-cp312-cp312-win_amd64.whl
uv add https://github.com/cgohlke/geospatial-wheels/releases/download/v2025.10.25/Shapely-2.1.2-cp312-cp312-win_amd64.whl
uv add https://github.com/cgohlke/geospatial-wheels/releases/download/v2025.10.25/Cartopy-0.25.0-cp312-cp312-win_amd64.whl

在 pyproject.toml 中固化（可选但推荐）

[tool.uv.sources]
# 只在 Windows 上用 Gohlke wheel
gdal = { url = "https://github.com/cgohlke/geospatial-wheels/releases/download/v2025.10.25/GDAL-3.11.4-cp312-cp312-win_amd64.whl", marker = "sys_platform == 'win32'" }
rasterio = { url = "https://github.com/cgohlke/geospatial-wheels/releases/download/v2025.10.25/rasterio-1.4.3-cp312-cp312-win_amd64.whl", marker = "sys_platform == 'win32'" }
pyproj = { url = "https://github.com/cgohlke/geospatial-wheels/releases/download/v2025.10.25/pyproj-3.7.2-cp312-cp312-win_amd64.whl", marker = "sys_platform == 'win32'" }
shapely = { url = "https://github.com/cgohlke/geospatial-wheels/releases/download/v2025.10.25/Shapely-2.1.2-cp312-cp312-win_amd64.whl", marker = "sys_platform == 'win32'" }

这样配置后，Windows 自动用 Gohlke wheel，其他系统（Linux/macOS）自动用 PyPI。

方案二：Windows 上安装 OSGeo4W 提供系统库（进阶）

什么时候用这个

坦白说，大多数人都不需要这个。但如果你：

想调试 GDAL 源码（比如研究 GDAL 的 bug）
想让 rasterio/fiona 用本地系统库而不是 wheel（性能敏感的场景）
已经被 Gohlke wheel 坑过了（虽然这种情况很少见）

那么这个方案可以试试。但要做好心理准备：这会很烦。

安装步骤

1. 下载 OSGeo4W 安装器

https://trac.osgeo.org/osgeo4w/

选择 64-bit 版本：osgeo4w-setup-x86_64.exe

2. Advanced Install（不要用 Express）

运行安装器，选择 Advanced Install：

Select Packages 界面，搜索并选择：
- gdal (版本 3.11.x)
- libgdal
- proj
- proj-data
- geos
安装到默认路径 C:\OSGeo4W64

3. 设置环境变量（永久生效）

系统环境变量（右键"此电脑" > 属性 > 高级系统设置 > 环境变量）：

变量名	值
`GDAL_DATA`	`C:\OSGeo4W64\share\gdal`
`PROJ_LIB`	`C:\OSGeo4W64\share\proj`
`PATH`	追加 `C:\OSGeo4W64\bin`

重启 PowerShell/VS Code。

4. 验证

import os
from osgeo import gdal, osr

os.environ['GDAL_DATA'] = r'C:\OSGeo4W64\share\gdal'
os.environ['PROJ_LIB'] = r'C:\OSGeo4W64\share\proj'

# 测试坐标系
srs = osr.SpatialReference()
srs.ImportFromEPSG(4326)
print("✓ GDAL ready")

优缺点

✅ 完整的 GDAL 生态 ✅ 后续 geopandas/rasterio 使用更稳定 ❌ 安装慢（~500MB） ❌ 环境变量容易出错

方案三：WSL (Ubuntu) 上升级系统 GDAL（最推荐）

问题：版本地狱

你满怀期待地在 WSL 装上了 GDAL，结果一跑代码，蹦出来这个：

Exception: Python bindings of GDAL 3.11.4 require at least libgdal 3.11.4, but 3.4.1/3.8.4 was found

这是啥意思？Ubuntu 仓库里的 GDAL 版本太老了。要么是 3.4.1，要么是 3.8.4，但你的 Python 绑定需要 3.11.4。就像两个程序员打架，一个说中文，一个说英文，根本沟通不了。

解决步骤

1. 升级系统 GDAL（用 ubuntugis PPA）

这里的关键是：别用官方 Ubuntu 仓库，用 ubuntugis 的 PPA，那里面的版本更新。

sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ubuntugis/ppa -y
sudo apt update
sudo apt install -y gdal-bin libgdal-dev proj-bin python3-gdal

2. 查看当前版本

gdal-config --version
# 输出: 3.8.4 (Ubuntu 24.04) 或 3.11.4 (有 ubuntugis 的系统)

3. 设置编译环境

export CPLUS_INCLUDE_PATH=/usr/include/gdal
export C_INCLUDE_PATH=/usr/include/gdal
export LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH

永久写入 ~/.bashrc：

echo 'export CPLUS_INCLUDE_PATH=/usr/include/gdal' >> ~/.bashrc
echo 'export C_INCLUDE_PATH=/usr/include/gdal' >> ~/.bashrc
source ~/.bashrc

4. 用 uv 安装 GDAL Python 绑定

# 匹配系统版本
gdal_version=$(gdal-config --version)
uv add "gdal==$gdal_version"
# 或指定 3.8.4
uv add "gdal==3.8.4"

5. 验证

python -c "from osgeo import gdal; print(gdal.__version__)"
# 输出: 3.8.4 ✓

为什么不必强上 3.11.4

GDAL 3.8.4 已支持所有现代功能
segment-geospatial、rasterio 等包都兼容 3.8+
强行编译 3.11.4 需要 30-60 分钟，收益微乎其微

方案四：Windows 上用 Miniconda（长期项目推荐，不熟悉 WSL）

场景

如果你只有 Windows 系统，不熟悉 WSL 或不想折腾双系统，但需要长期做地理空间项目，用 Miniconda + conda-forge 一个就够了。

为什么选 Conda 而不是 Gohlke Wheel

Gohlke Wheel 快（30 秒），但只适合快速原型
Conda 稍慢（5 分钟），但一次配置，永久无忧
所有依赖（GDAL、rasterio、geopandas、leafmap）都完全兼容
一个 environment.yml 文件，其他电脑直接 conda env create 秒复现
不需要手动设置 GDAL_DATA、PROJ_LIB 等环境变量

安装步骤

1. 安装 Miniconda

下载地址：https://docs.conda.io/projects/miniconda/en/latest/

选择 Windows x64 版本，安装到默认路径。

2. 创建 `environment.yml`

在你的项目根目录创建 environment.yml：

name: geo-projects
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.12
  - gdal>=3.8
  - proj
  - geos
  - fiona
  - rasterio
  - pyogrio
  - shapely
  - geopandas
  - cartopy
  - netcdf4
  - rtree
  - jupyterlab
  - pip
  - pip:
      # 如果有纯 Python 包需要最新版本，用 pip 装
      - segment-geospatial[samgeo2]>=0.15.2
      - leafmap>=0.57.9
      - torch>=2.3

3. 创建环境

conda env create -f environment.yml
conda activate geo-projects

4. 验证

python -c "from osgeo import gdal; print(gdal.__version__)"
# 应输出 3.8.4 或更高版本 ✓

优势

✅ 一个文件管理一切：只需维护 environment.yml
✅ 完全兼容：Windows、WSL、macOS 同一个配置文件
✅ 永不版本冲突：conda 自动处理所有 C++ 依赖
✅ 无需环境变量：没有 GDAL_DATA、PROJ_LIB 麻烦
✅ 一键复现：新电脑或给同事只需 conda env create -f environment.yml
✅ 简单直观：比 Conda + uv 混合更省心

日常工作流

# 每次打开项目
conda activate geo-projects
jupyter lab

# 或直接运行脚本
python your_script.py

# 需要新包？直接加到 environment.yml，然后
conda env update -f environment.yml

各方案适用场景

你的场景	推荐方案	理由
快速做原型、单人项目、不想装任何东西	方案一（Gohlke Wheel）	30 秒搞定，最小化依赖
需要调试 GDAL 源码、多版本并存	方案二（OSGeo4W）	完整开发环境
只有 Windows，不熟悉 WSL，长期项目	方案四（Miniconda）	一个文件管理一切，永不版本冲突
有 WSL，想要最快速度和简洁体验	方案三（系统 GDAL）	WSL 最大化速度，又超简单

常见坑与排查

坑 1: "gdal.h: No such file or directory"

你遇到这个错误说明什么：编译器找不到 GDAL 的头文件。在 Windows 上，这是很正常的，因为你的系统根本没装。

快速修复：

方案一：用 Gohlke wheel（推荐，最快）
方案二：装 OSGeo4W（麻烦，但管用）

坑 2: "proj.db not found"

你遇到这个错误说明什么：GDAL 找不到投影系统的数据库。通常是环境变量没设好。

快速修复：检查你的环境变量

import os
from osgeo import gdal
print(gdal.GetConfigOption('GDAL_DATA'))      # 应该指向一个真实的目录
print(os.environ.get('PROJ_LIB'))             # 同样

如果输出是 None 或空，那就是环境变量没装上。回去按照上面的步骤重新设置。

坑 3: Python 3.13 上 GDAL wheel 找不到

你遇到这个错误说明什么：你用了太新的 Python。PyPI 的 wheel 更新慢，官方还没给 3.13 编译 wheel。

快速修复：

最好的办法：用 Gohlke wheel（他更新得快）
次好的办法：降级到 Python 3.12（生态最完善）
最后的办法：在 WSL 用 conda（会自动编译）

坑 4: 每次 `uv sync` 都要重新编译 GDAL

你遇到这个错误说明什么：你的 pyproject.toml 里指定的 GDAL 版本跟系统装的不一样。每次同步，uv 都试图重新编译匹配版本。很烦。

快速修复：在 pyproject.toml 里加一行，强制固定版本

[tool.uv.overrides]
gdal = "3.8.4"  # 强制所有依赖都用 3.8.4，跟系统保持一致

这样 uv 就不会每次都试图「升级」GDAL 了。

总结：选择适合你的「一个方案」

我花了一整天在这上面踩坑。真的，一整天。所以我总结出最重要的一条教训：

选择一个方案，坚持一个。别特么混用。

我的血泪教训是这样的：

❌ 先装 Gohlke wheel，还能用，但维护了一阵子后版本乱了
❌ 然后试了 OSGeo4W，装是装上了，但环境变量各种诡异bug，改了半天还没完全好
❌ 再后来想聪明一点，Conda + uv 混合，结果彻底地狱，两个包管理器打架
✅ 最后整到 WSL，一行命令，再也没问题过

实战建议

如果你只有 Windows + 不熟悉 WSL： 别折腾了，装 Miniconda（就 20MB，小得不行）。然后：

创建个 environment.yml 文件
conda env create -f environment.yml
搞定。从此以后再也不用手动装 GDAL 了

如果你能用 WSL（推荐）：

sudo apt update && sudo apt install gdal-bin python3-gdal
python -m venv .venv
source .venv/bin/activate

完。

最后的碎碎念：

就维护一个配置文件（environment.yml 或系统）
永远别想「我同时用 uv、conda、系统包」，那是自杀
99% 的版本冲突都是自己搞出来的。真的。

快速命令表

你的选择	命令
Gohlke 一分钟	`uv add https://github.com/cgohlke/geospatial-wheels/releases/download/v2025.10.25/GDAL-3.11.4-cp312-cp312-win_amd64.whl`
Windows 用户 + 长期	装 Miniconda，创建 `environment.yml`，`conda env create -f environment.yml`
WSL 用户 + 专业	`sudo apt update && sudo apt install gdal-bin python3-gdal` + `python -m venv .venv`

延伸阅读

最后的话：GDAL 在 Windows 上的问题已经折磨开发者 10 多年。官方没有解决，Gohlke 和 conda-forge 成了救世主。如果你是做地理空间的长期项目，强烈建议现在就投入 5 分钟配置方案四，以后你会感谢自己。

问题背景

核心原因分析

1. Windows 上的困局

2. Python 版本问题

3. WSL 上的版本不匹配

解决方案对比

方案对比表

方案一：Windows 上用 Gohlke 预编译 Wheel（最快）

问题描述

解决步骤

1. 下载预编译 wheel

2. 直接用 uv 安装（支持在线链接）

3. 验证安装

为什么这个方法最爽

其他常用包的 Wheel 列表

在 pyproject.toml 中固化（可选但推荐）

方案二：Windows 上安装 OSGeo4W 提供系统库（进阶）

什么时候用这个

安装步骤

1. 下载 OSGeo4W 安装器

2. Advanced Install（不要用 Express）

3. 设置环境变量（永久生效）

4. 验证

优缺点

方案三：WSL (Ubuntu) 上升级系统 GDAL（最推荐）

问题：版本地狱

解决步骤

1. 升级系统 GDAL（用 ubuntugis PPA）

2. 查看当前版本

3. 设置编译环境

4. 用 uv 安装 GDAL Python 绑定

5. 验证

为什么不必强上 3.11.4

方案四：Windows 上用 Miniconda（长期项目推荐，不熟悉 WSL）

场景

为什么选 Conda 而不是 Gohlke Wheel

安装步骤

1. 安装 Miniconda

2. 创建 environment.yml

3. 创建环境

4. 验证

优势

日常工作流

各方案适用场景

常见坑与排查

坑 1: "gdal.h: No such file or directory"

坑 2: "proj.db not found"

坑 3: Python 3.13 上 GDAL wheel 找不到

坑 4: 每次 uv sync 都要重新编译 GDAL

总结：选择适合你的「一个方案」

实战建议

快速命令表

延伸阅读

2. 创建 `environment.yml`

坑 4: 每次 `uv sync` 都要重新编译 GDAL