1. 拿到老师代码先别急着跑环境与库版本兼容的真实场景你从老师或者学长那里拿到一份代码压缩包解压之后看到一堆.py文件、一个requirements.txt可能还有个README。双击运行第一行就报ModuleNotFoundError: No module named osgeo或者更隐蔽的——代码能跑但结果全是NaN或者画出来的图跟老师演示的完全不一样。这类问题九成不是代码逻辑错了而是环境不对、库版本不兼容。我带的几届学生里最常见的翻车链路是这样的电脑上早就装了 Anacondabase 环境里堆了几十个包直接python xxx.py跑结果 GDAL 和 rasterio 版本对不上geopandas 又依赖了另一个版本的 shapely最后报错信息指向一个你根本没 import 过的库。所以这篇就按“从零建隔离环境 → 绑定 PyCharm 解释器 → 锁版本 → 验证兼容 → 排错”的完整链路走一遍重点放在库版本兼容这个真正的坑上。适合刚拿到课程代码、对 conda 和 PyCharm 都还不太熟的同学也适合已经跑通但想搞清楚“为什么当时会报错”的人。核心检索词先摆出来Anaconda 创建隔离环境、conda 库版本兼容、PyCharm 绑定解释器、GDAL/rasterio/geopandas 版本冲突排查。下面每一步都给可复制的命令和配置文件骨架你照着改路径就能用。2. 前置准备Anaconda 装好之后先做这三件事Anaconda 装完开始菜单里会有 Anaconda PromptWindows或者终端里能直接调 condamacOS/Linux。我建议所有 conda 操作都在 Anaconda Prompt 里做不要用系统自带的 cmd 或 PowerShell因为环境变量路径容易乱。PyCharm 那边只是用来写代码和调试建环境、装库这些事交给命令行更可控。第一件事确认 conda 可用并且版本别太老conda --version conda info --envsconda info --envs会列出你现有的所有环境base 前面有个星号。第二件事配置国内镜像源不然装 GDAL 这种包会慢到怀疑人生。清华的 conda-forge 镜像对地理空间类库覆盖比较全conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/msys2/ conda config --set show_channel_urls yes conda config --show channels最后一条会打印当前生效的 channel 顺序确认 conda-forge 在里面。第三件事如果你后续要用到统一的 Key/API 通道来调用模型做代码辅助或者文档生成可以先把 TaoToken 的配置骨架准备好。它的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 入口是 https://taotoken.net/api 。注意这里只是配置骨架示范不是让你现在就去调先把环境跑通再说。提示镜像源配置是全局的写在~/.condarcWindows 是C:\Users\你的用户名\.condarc。如果后面某个包在 conda-forge 里找不到再临时加其他 channel不要一上来堆一堆源容易触发依赖解析冲突。3. 可复制配置environment.yml、requirements.txt 与 settings.json 骨架3.1 用 environment.yml 一次性锁定环境老师给的代码如果带了environment.yml直接用它建环境最省事。如果没有就按下面这个骨架自己写一份。关键点是python3.9和地理空间库的版本要互相兼容GDAL 3.10.x 配 rasterio 1.4.x、geopandas 1.0.x 这一组是实测能跑通的组合name: course_env channels: - https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge - defaults dependencies: - python3.9 - gdal3.10.2 - rasterio1.4.3 - geopandas1.0.1 - matplotlib3.9.4 - seaborn0.13.2 - statsmodels0.14.4 - esda2.5.1 - splot1.1.7 - pip - pip: - some-pip-only-package1.2.3保存为environment.yml然后在 Anaconda Prompt 里执行conda env create -f environment.yml conda activate course_envconda env create会一次性解析所有依赖比一个个conda install更不容易出现版本漂移。如果你只想手动建再逐个装那就conda create -n course_env python3.9 conda activate course_env conda install -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge gdal3.10.2 rasterio1.4.3 geopandas1.0.1注意-c后面跟 channel URL 可以临时指定源适合只给某个包装特定 channel 的场景。3.2 requirements.txt 作为 pip 补充有些包 conda-forge 里没有或者老师代码里明确写了 pip 安装那就用requirements.txtnumpy1.26.4 pandas2.2.2 shapely2.0.4 pyproj3.6.1执行pip install -r requirements.txt但这里有个大坑不要混用 conda 和 pip 装同一个包。比如你用 conda 装了 gdal又用 pip 装了一个不同版本的 gdalconda list和pip list会各显示各的实际 import 的时候加载的是哪一个完全看路径顺序。所以原则是能用 conda 装的优先 condaconda 没有的再用 pip并且 pip 装完之后立刻用pip check验证。3.3 PyCharm 绑定解释器与 settings.json 骨架PyCharm 里新建项目或者打开老师代码文件夹后进入File → Settings → Project → Python Interpreter点齿轮选Add然后选Conda Environment再选Existing environment解释器路径指向Windows: C:\Users\你的用户名\anaconda3\envs\course_env\python.exe macOS/Linux: /Users/你的用户名/anaconda3/envs/course_env/bin/python绑定好之后PyCharm 右下角会显示当前解释器名字。如果你用 VS Code可以在项目根目录建.vscode/settings.json{ python.defaultInterpreterPath: C:\\Users\\你的用户名\\anaconda3\\envs\\course_env\\python.exe, python.terminal.activateEnvironment: true, python.linting.enabled: true }这样终端启动时会自动激活 conda 环境不用每次手动conda activate。3.4 TaoToken 配置骨架仅示范接入方式如果你在排查过程中想让模型帮你读报错、生成修复建议可以在项目里放一个config.toml骨架把 Key 和 API 地址集中管理。注意不要把真实 Key 提交到 git[taotoken] api_base https://taotoken.net/api api_key sk-你的Key model claude-sonnet [project] python_env course_env对应的 Python 读取方式import tomllib with open(config.toml, rb) as f: cfg tomllib.load(f) api_base cfg[taotoken][api_base] api_key cfg[taotoken][api_key]Key 的申请和管理在控制台里做入口是 https://taotoken.net/console 。如果你后面要长期用模型辅助写代码、跑 Agent可以看 Coding Planhttps://taotoken.net/coding-plan 。模型对话入口在 https://taotoken.net/models 。这些只是配置骨架环境没跑通之前不用急着接。4. 验证请求conda list、pip check 与真实 import 测试环境建好、库装完怎么确认版本兼容真的修好了三步验证。第一步conda list看装了哪些包、什么版本、来自哪个 channelconda activate course_env conda list输出里重点看 gdal、rasterio、geopandas、shapely、pyproj 这几行的版本号和 channel 列。如果 channel 列显示conda-forge说明是从镜像源装的如果显示pypi说明是 pip 装的要留意有没有和 conda 版本冲突。第二步pip check检查依赖一致性pip check正常输出是No broken requirements found.。如果出现类似geopandas 1.0.1 requires shapely2.0.0, but you have shapely 1.8.5那就是版本冲突需要按提示升级或降级对应包。第三步真实 import 测试。写一个check_env.pyimport sys print(sys.executable) import gdal import rasterio import geopandas import matplotlib import seaborn import statsmodels import esda import splot print(gdal:, gdal.__version__) print(rasterio:, rasterio.__version__) print(geopandas:, geopandas.__version__) print(matplotlib:, matplotlib.__version__) print(seaborn:, seaborn.__version__) print(statsmodels:, statsmodels.__version__) print(esda:, esda.__version__) print(splot:, splot.__version__)运行python check_env.py如果全部 import 成功并且版本号打印出来说明环境层面已经通了。这时候再去跑老师的代码ModuleNotFoundError: No module named osgeo这类报错基本就消失了。注意osgeo是 GDAL 的 Python 绑定装 gdal 的时候会自动带上如果还报这个错多半是 PyCharm 解释器没绑对回去检查第 3.3 步。5. 本篇常见错排查从报错信息定位到具体库5.1 ModuleNotFoundError: No module named osgeo这个报错出现频率最高。原因通常有三个一是根本没装 gdal二是装了但装在了 base 环境当前用的是 course_env三是 PyCharm 解释器指向了系统 Python 而不是 conda 环境。排查顺序先conda list | findstr gdalWindows或conda list | grep gdalmacOS/Linux确认当前环境里有 gdal再python -c import sys; print(sys.executable)确认解释器路径最后去 PyCharm 里核对解释器设置。5.2 ImportError: DLL load failed while importing _gdalWindows 上常见一般是 GDAL 的 C 库和 Python 绑定版本不匹配或者 PATH 里有多个 GDAL。解决办法是彻底删掉环境重建conda deactivate conda env remove -n course_env conda env create -f environment.yml重建时确保只从 conda-forge 装 gdal不要 pip 再装一遍。5.3 pip check 报 shapely 版本冲突geopandas 1.0.x 要求 shapely2.0.0但有些老代码的 requirements 里锁了 shapely1.8.5。这时候不要直接改 requirements而是先确认老师代码是否真的依赖老版本 shapely。如果只是 requirements 没更新直接conda install -c conda-forge shapely2.0.4 pip check如果老师代码确实用了 shapely 1.x 的 API那就得降 geopandas 到 0.14.x这时候版本组合要重新验证建议用conda install geopandas0.14.4 shapely1.8.5让 conda 自己解析依赖。5.4 PyCharm 里跑正常命令行跑报错反过来也常见。原因是 PyCharm 用的解释器和终端里python指向的不是同一个。在 PyCharm 的 Terminal 里执行where pythonWindows或which python对比 Settings 里的解释器路径。不一致就改 Settings或者直接在 PyCharm Terminal 里conda activate course_env。5.5 conda install 卡在 Solving environment这是 conda 依赖解析慢不是死机。可以加--no-deps跳过依赖检查但风险是依赖没装全或者改用 mambaconda install -n base -c conda-forge mamba mamba install -c conda-forge gdal3.10.2 rasterio1.4.3mamba 的解析速度快很多适合反复试版本组合的场景。6. 环境跑通之后把 Key 和 API 通道固定下来环境跑通、check_env.py全部打印出版本号之后你后面大概率还会遇到“想让模型帮忙读报错”“想批量生成测试数据”“想接一个 Agent 自动跑实验”这类需求。这时候把 Key 和 API 通道固定下来会省很多事。TaoToken 在这里的角色是统一入口一个 Key 可以走模型对话、代码补全、Agent 调用不用每个服务单独配一套鉴权。接入文档在 https://taotoken.net/doc API Key 管理在 https://taotoken.net/api-keys 。如果你用 Claude Code 这类编码工具Anthropic 兼容入口的配置参考 https://taotoken.net/ClaudeCodeAnthropic 。长期做编码和 Agent 的话Coding Plan 的额度模型比按次调用更划算入口是 https://taotoken.net/coding-plan 。最后给一个我自己的习惯每次帮别人排查完环境都会把最终能跑通的environment.yml和conda list输出一起存到项目根目录的env_backup/里。下次换电脑或者过几个月再跑直接conda env create -f environment.yml不用重新试版本。这个习惯比任何排错技巧都管用。