010. 重建 Conda 环境与 PyCharm 运行配置

学习目标

这一节补充一次完整的本地后端环境重建流程。

学完后，你应该能理解：

• PyCharm 新版本安装后如何重新配置解释器；
• Conda 环境坏了为什么可以重新创建；
• Poetry、Conda、pip 分别在依赖安装里做什么；
• psycopg 为什么和 PostgreSQL 连接有关；
• 为什么推荐用 PyCharm 运行配置启动后端；
• Windows 下为什么可以使用 Git Bash 作为终端。

什么时候需要重建环境？

Python 项目依赖比前端更容易遇到环境问题。

可能出现：

• 某个包没装上；
• 解释器选错；
• Conda 环境损坏；
• 网络导致依赖下载中断；
• 权限问题导致包写入失败；
• PyCharm 运行配置指向旧环境。

如果排查成本太高，可以重新创建一个干净 Conda 环境。

这和前端删除 node_modules 后重新 pnpm install 类似，只是 Python 环境更强调解释器版本和虚拟环境隔离。

安装或更新 PyCharm

如果重新安装 PyCharm，不要随便删除旧版本目录，尤其是里面还有配置或激活信息时。

Windows 上如果不是必须开机启动的软件，可以优先安装到非 C 盘，减少系统盘压力。

安装完成后，先确认：

• PyCharm 能正常打开；
• 账号或授权状态正常；
• 项目目录能打开；
• 设置页面能找到 Python Interpreter。

创建新的 Conda 环境

如果旧环境叫 ai2，这次可以创建一个新环境，例如 ai3。

示例：

conda create -n ai3 python=3.11
conda activate ai3

环境名前面出现 ai3，说明当前终端已经激活这个环境。

Python 版本继续使用 3.11，因为项目依赖以这个版本为基准，过新或过旧都可能带来兼容问题。

安装 Poetry

Poetry 是 Python 项目的依赖管理工具。

先在当前 Conda 环境里安装 Poetry：

pip install poetry

这里的 pip install poetry 只是在当前 ai3 环境里安装 Poetry，不会影响其他 Conda 环境。

在项目根目录安装依赖

进入后端项目根目录后执行：

poetry install

Poetry 会读取项目里的依赖配置文件和锁定文件，安装项目需要的包。

要注意：命令必须在项目根目录执行。否则 Poetry 找不到正确的配置文件，就不会按当前项目安装依赖。

安装 PostgreSQL 驱动

后端连接 PostgreSQL 需要驱动包，例如 psycopg。

如果缺少这个包，后端启动时可能报模块不存在或数据库连接相关错误。

Windows 下可以优先用 Conda 安装，成功率通常更高；Linux 或 macOS 下可以尝试用 pip 安装。

关键不是死记某个命令，而是理解：

缺哪个包，就要确认当前解释器环境里是否真的安装了这个包。

在 PyCharm 里检查包

PyCharm 的解释器页面可以看到当前环境里安装了哪些包。

如果报错说缺少某个包，先确认：

• 当前项目选的是不是 ai3；
• ai3 里有没有这个包；
• 包是不是装到了别的环境；
• 终端里激活的环境和 PyCharm 运行配置里的解释器是否一致。

很多 Python 新手的问题不是“包没装”，而是“包装到了另一个环境”。

使用 Git Bash 终端

Windows 自带终端命令和 Linux / macOS 不完全一致。

如果已经安装 Git，可以使用 Git Bash。

Git Bash 的命令习惯更接近 Linux / macOS，例如：

• ls
• pwd
• cd
• cat

课程里大量服务器命令也是 Linux 风格，用 Git Bash 会更顺手。

可以在 PyCharm 的 Terminal 设置里，把默认终端改成 Git Bash。

绑定 PyCharm 解释器

在 PyCharm 设置里找到 Python Interpreter，把项目解释器切换到新创建的 ai3。

切换后，PyCharm 会重新索引当前环境里的包。

如果某些包标红，先不要急着改代码，优先确认依赖是否安装完整。

配置运行入口

后端入口文件在 app 目录下，例如 server.py。

第一次右键运行时，PyCharm 可能自动生成一个运行配置，但工作目录不一定正确。

需要检查：

• Script 是不是入口文件；
• Python Interpreter 是不是 ai3；
• Working Directory 是不是项目根目录；
• 环境变量是否读取正确。

如果工作目录错了，项目可能找不到 .env 或内部模块。

为什么不推荐直接命令行跑？

命令行当然可以跑 Python 项目，但当前阶段更推荐用 PyCharm 运行配置。

因为后端启动不只是执行一个 Python 文件，还涉及：

• 工作目录；
• Python 解释器；
• 环境变量；
• 依赖路径；
• 项目模块导入；
• FastAPI 启动参数。

PyCharm 运行配置能把这些信息固定下来，减少每次手动输入命令带来的错误。

验证后端启动

运行成功后，应能看到数据库连接成功信息，并可以访问 FastAPI 接口文档。

如果 MySQL、PostgreSQL、Milvus、Redis 都能连接，说明本地后端运行环境恢复正常。

这节的目标不是新增业务功能，而是把“环境坏了如何重建”这件事走通。