macOS开发GeoDjango使用osgeo/gdal镜像运行时报gdal304.dll错误

错误原因 #

• 最核心的诱因是Django配置中存在硬编码的Windows平台GDAL路径：大概率是你的settings.py里手动写了GDAL_LIBRARY_PATH = 'C:\OSGeo4W\bin\gdal304.dll'，这个配置是Windows环境下的适配参数，而你的容器是Linux系统，完全不存在该路径，因此Django加载GDAL绑定时直接报错。
• 依赖锁文件跨平台适配问题：如果你的Pipfile.lock或requirements.txt是在Windows环境下生成的，锁文件中的GDAL Python绑定版本是适配Windows系统的，放到Linux容器中运行时会默认查找Windows平台的dll库文件。
• Dockerfile存在版本冲突问题：你使用的osgeo/gdal基础镜像默认自带Python3.8，但你手动安装了Python3.6，后续apt安装的python3-gdal是适配Python3.6的版本，而pip安装的Django等依赖是运行在Python3.8下的，版本不匹配导致Django无法正确识别系统中已安装的GDAL库路径。

修复方案 #

1. 修复Django配置
   删掉settings.py中硬编码的GDAL_LIBRARY_PATH、GEOS_LIBRARY_PATH等Windows专属路径配置，容器内的GDAL库为标准安装路径，Django可自动识别。如果需要兼容本地多环境开发，可以增加系统判断：

import os
if os.name == 'nt':
    # 仅Windows环境下加载该路径配置
    GDAL_LIBRARY_PATH = r'C:\OSGeo4W\bin\gdal304.dll'

2. 修正Dockerfile版本冲突问题
   移除冗余的Python3.6安装步骤，直接使用基础镜像自带的Python3.8，减少不必要的依赖冲突，修改后的base阶段如下：

FROM osgeo/gdal as base
RUN set -xe \
    && apt-get update \
    && apt-get install -y --no-install-recommends python3-pip gcc gdal-bin python3-gdal \
    && rm -rf /var/lib/apt/lists/* \
    && pip3 install --upgrade pip

3. 修复跨平台依赖问题
   容器构建阶段直接使用Pipfile安装依赖，不需要提前导出requirements.txt，避免本地锁文件的跨平台适配问题，修改后的依赖安装阶段如下：

FROM base AS final
WORKDIR /code
COPY Pipfile /code/
COPY Pipfile.lock /code/
RUN pip install pipenv  \
    && pipenv install --system --deploy --ignore-pipfile
COPY . /code/
ENTRYPOINT ["/bin/bash", "/code/entrypoint.sh"]

另外可将GDAL Python包从你的依赖声明中移除，容器内已经通过apt安装了适配系统的python3-gdal，不需要重复通过pip安装，避免版本冲突。

内容的提问来源于stack exchange，提问作者smrf