Docker部署含PostGIS依赖的Django项目GDAL安装报错处理

我来帮你搞定这个Docker里的GDAL依赖坑，这在搭配PostGIS的Django项目部署中特别常见，咱们一步步来解决：

核心问题分析 #

你遇到的两个错误本质是关联的：

• FileNotFoundError: 找不到gdal-config：因为Docker的Python镜像默认没有安装GDAL的系统级库，pip编译gdal包时需要这个工具来定位头文件和库文件。
• E: Unable to locate package libgdal-dev：大概率是你用的python:3基础镜像对应的Debian版本太新（比如Bookworm/Buster），这些版本里的libgdal-dev版本已经不是你需要的2.2.3，或者你没先更新apt源导致找不到包。

解决方案：修正Dockerfile #

1. 选择匹配GDAL版本的基础镜像 #

因为你需要gdal==2.2.3，而Debian Stretch（旧稳定版）的官方源里正好是这个版本，所以咱们换用对应Python版本的Stretch镜像。Django 2.1.5支持Python 3.5-3.7，所以用python:3.7-stretch最合适。

2. 安装系统依赖并配置环境变量 #

先更新apt源，安装编译GDAL和psycopg2需要的所有系统库，然后设置环境变量让编译器能找到GDAL的文件。

完整Dockerfile示例 #

# 选择匹配GDAL 2.2.3的基础镜像
FROM python:3.7-stretch

# 设置工作目录
WORKDIR /app

# 更新apt源并安装系统依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    libgdal-dev \
    libpq-dev \
    gcc \
    python3-dev \
    && rm -rf /var/lib/apt/lists/*  # 清理缓存减小镜像体积

# 设置GDAL相关环境变量，让pip编译时能找到头文件和库
ENV CPLUS_INCLUDE_PATH=/usr/include/gdal
ENV C_INCLUDE_PATH=/usr/include/gdal

# 先安装GDAL（版本要和系统库匹配），再安装其他依赖
RUN pip install --no-cache-dir gdal==2.2.3
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制项目代码（根据你的项目结构调整）
COPY . .

# 启动命令（示例，根据你的项目需求修改）
CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

关键细节说明 #

• 为什么指定Stretch镜像？：不同Debian版本的libgdal-dev版本不同，Stretch对应GDAL 2.2.3，正好匹配你要安装的gdal==2.2.3，避免版本不兼容的问题。
• 为什么要先装GDAL再装requirements？：有些情况下，requirements.txt里的其他包（比如Django）可能会间接依赖GDAL，先单独安装GDAL能确保编译过程顺利。
• 添加libpq-dev的原因：psycopg2编译需要PostgreSQL的系统库，这个包能解决psycopg2安装时的编译错误。

如果还是遇到问题，可以尝试在安装GDAL时显式指定编译选项：

RUN pip install --no-cache-dir --global-option=build_ext --global-option="-I/usr/include/gdal" gdal==2.2.3

内容的提问来源于stack exchange，提问作者Sam B.