3.1 环境配置与依赖管理

3.1 环境配置与依赖管理

地基不牢，后面全塌

装包之前先确认环境，这步看着啰嗦，却是大多数"在我机器上能跑"问题的根源。Cognee 依赖一些对 Python 版本敏感的库（图数据库驱动、异步框架），用错版本会装到一半报错。

这一节是第三章的第一站，目标是给你一个干净、可复现的 Python 环境。

Python 版本与虚拟环境

Cognee 要求 Python 3.10 及以上。我们强烈建议用虚拟环境隔离，避免和你机器上别的项目依赖互相踩脚。用 venv 或 conda 都行，下面用 venv 示意。

# 确认 Python 版本
python --version

# 创建并激活虚拟环境
python -m venv cognee-env
source cognee-env/bin/activate     # Windows 用 cognee-env\Scripts\activate

# 激活后提示符前会出现 (cognee-env)
which python
# .../cognee-env/bin/python
​

激活虚拟环境后，所有 pip install 都只装进这个隔离环境。哪天环境乱了，删掉文件夹重来，不影响系统 Python。

依赖管理的两种姿势

用 requirements 锁版本

如果你要给别人复现，或上生产，导出依赖清单：

# 在装好 cognee 的虚拟环境里
pip freeze > requirements.txt
cat requirements.txt

# 别人复现时
pip install -r requirements.txt
​

锁版本的价值在于：Cognee 迭代快，某个图库驱动的 breaking change 可能让"上周能跑"的脚本这周挂掉。锁定后能先把问题隔离在"是不是我代码改了"，而不是"是不是依赖飘了"。

案例：新成员的环境复现

背景：团队里新同事要跑通现有 Cognee 项目，但不想被依赖问题卡三天。

操作：直接吃现成的锁定文件。

git clone <项目仓库>
cd <项目>
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt   # 一键复现团队环境
python -c "import cognee; print(cognee.__version__)"
# 0.1.42
​

结果：十分钟内装好，版本和老员工完全一致，免去"你那是老版"的扯皮。

解读：环境配置的本质是"可复现性"。把依赖当代码管，问题才有稳定基线。

变式：若公司用私有 PyPI 镜像，把 pip install 指向内网源，既加速又避免外网不稳。这是生产里常见的变体。

一个常见翻车：依赖冲突比装不上更烦

装包失败好排查，真正磨人的是"装上了但跑起来行为怪异"——往往是两个库各自锁了不兼容的版本，Python 在运行时才暴露。类比到建筑：两种规格的钢筋混用，封顶前看不出，受力就裂。虚拟环境的作用就是让每个项目有独立"材料库"，互不串味。

# 用依赖清单锁定，保证可复现（示意）
pip freeze > requirements.lock
# 新机器复原一模一样的环境
pip install -r requirements.lock
​

Cognee 对图数据库驱动版本敏感，锁版本能避免"同事机器能跑、你机器报错"的经典扯皮。

⚠️ 别在系统 Python 里直接 pip install cognee——会污染全局，将来别的老项目可能突然崩。

💡 环境问题的第一定律：先确认"是不是环境不对"再改代码。多数 ImportError 重装对应包就好，别去改业务逻辑。

一个工具选择：venv 还是 conda

虚拟环境两种主流：venv 轻、随 Python 走；conda 能管非 Python 依赖（如某些图库的本地库）。若你的图后端需要系统级依赖，conda 省心；纯 Python 栈 venv 足够。选错只是麻烦，不致命，但选对省时间。

⚠️ 别在容器里再套一层 conda 又套 venv——层级越多，环境越难复现，出问题更难查。

💡 环境方案写进 README 第一步，新人照做三分钟起来，比口口相传稳。

一个收尾：环境即文档

好的环境配置本身就是文档——新人照着能复现，机器换了能重建。把环境步骤写进 README 且可脚本化，比老员工脑里的"我记得要装那个"可靠百倍。

⚠️ 别把环境知识锁在个人脑子里——那人一离职，团队环境能力就断层。

💡 环境搭建脚本化后跑一遍 CI，证明"按文档确实能起来"，而非仅作者能跑。

一个对照：环境出错的两种信号

环境问题的信号分两类：装包阶段报错（依赖冲突、编译失败）和运行阶段诡异（导入成功但行为不对）。前者好查，后者磨人。区分信号能少走弯路：装不上就查依赖树，跑不对先怀疑版本错配。

⚠️ 别把"运行诡异"当代码 bug 改——八成是环境版本不对，改业务代码只会越改越乱。

💡 环境异常先建最小复现：新建干净 venv 只装 cognee 跑示例，能跑说明原环境脏。

本节要点回顾

• Cognee 需 Python 3.10+，务必用虚拟环境隔离。
• 直接装适合试水，锁 requirements 适合协作与生产。
• 依赖当代码管，问题才有稳定基线。

⚠️ 别在系统 Python 里直接装 cognee。依赖冲突会拖垮你机器上别的项目。

💡 装完第一件事是 pip freeze > requirements.txt，这习惯能救你无数次。