4. Python 环境准备：Python 3.10+ 安装、虚拟环境配置与依赖管理
在开始编写欺诈图谱阈值巡检脚本之前，必须搭建一个干净、可复现的 Python 运行环境。本章将指导你完成从 Python 解释器安装到依赖锁定的全流程，确保后续章节的代码能在任何机器上一致执行。
4.1 环境版本要求与选择
本课程所有代码基于 Python 3.10+ 开发，推荐使用 Python 3.11 或 3.12。Python 3.10 引入了结构模式匹配（match-case）和更精确的错误提示，这些特性在解析图谱规则时会频繁使用。
| 特性 | Python 3.10 | Python 3.11 | Python 3.12 |
|---|---|---|---|
| 结构模式匹配 | ✅ 正式引入 | ✅ 优化 | ✅ 优化 |
| 异常组 (ExceptionGroup) | ✅ | ✅ | ✅ |
| 性能提升 | 基准 | 约 10-60% | 约 5-10% |
| 类型注解语法 | 基础 | Self/Literal 增强 | 泛型类语法简化 |
| 官方支持截止 | 2026-10 | 2027-10 | 2028-10 |
版本选择建议： 如果你的生产环境允许，优先选择 Python 3.11。它在性能与语法特性之间取得了最佳平衡，且与主流数据科学库（pandas、networkx）兼容性最好。
4.2 安装 Python 3.10+
根据操作系统选择安装方式：
- Windows： 从 python.org 下载安装包，安装时务必勾选 "Add Python to PATH"。
- macOS： 推荐使用
brew install python@3.11，或从官网下载安装器。 - Linux (Ubuntu/Debian)： 使用 deadsnakes PPA：
sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt install python3.11 python3.11-venv python3.11-dev。
安装完成后，验证版本：
python3 --version
# 输出示例: Python 3.11.9
python3 -m ensurepip --version
# 确保 pip 已安装
4.3 虚拟环境配置
虚拟环境隔离项目依赖，避免不同项目间的包版本冲突。本课程统一使用 Python 内置的 venv 模块，无需额外安装。
4.3.1 创建虚拟环境
在项目根目录下执行：
# 创建名为 .venv 的虚拟环境（推荐放在项目根目录）
python3 -m venv .venv
# 激活环境
# Linux/macOS:
source .venv/bin/activate
# Windows (CMD):
.venv\Scripts\activate.bat
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
激活后，终端提示符前会出现 (.venv) 标识，表示当前处于虚拟环境中。
4.3.2 虚拟环境结构说明
下图展示了虚拟环境的核心目录结构与 Python 解释器隔离机制：
关键理解： 激活虚拟环境后，
python 和 pip 命令指向的是 .venv/bin/ 下的副本，而非系统全局路径。所有通过 pip install 安装的包都会被写入 lib/python3.11/site-packages/，完全隔离。
4.4 依赖管理：requirements.txt
依赖管理是自动化运维的基石。本课程使用 requirements.txt 文件锁定项目依赖，确保 CI/CD 流水线或同事拉取代码后能一键复现环境。
4.4.1 生成 requirements.txt
在虚拟环境激活状态下，安装完所有依赖后执行：
# 冻结当前环境的所有包及其精确版本
pip freeze > requirements.txt
生成的 requirements.txt 内容示例：
networkx==3.2.1
pandas==2.2.0
numpy==1.26.3
matplotlib==3.8.2
pyyaml==6.0.1
schedule==1.2.0
loguru==0.7.2
pydantic==2.5.3
4.4.2 从 requirements.txt 安装依赖
在新环境中复现依赖：
# 创建并激活虚拟环境后执行
pip install -r requirements.txt
4.4.3 依赖分类管理（进阶）
对于生产级项目，建议按用途拆分依赖文件：
| 文件名 | 用途 | 示例包 |
|---|---|---|
requirements/base.txt |
生产环境核心依赖 | networkx, pandas, pyyaml |
requirements/dev.txt |
开发/测试工具 | pytest, black, mypy, pre-commit |
requirements/ci.txt |
CI 流水线专用 | coverage, pytest-xdist |
通过 -r 参数实现继承：
# dev.txt 内容示例
-r base.txt
pytest==8.0.0
black==24.1.1
避坑提醒： 不要直接使用
pip freeze > requirements.txt 导出包含系统级包或无关依赖的环境。建议在干净的虚拟环境中只安装项目所需包后再冻结。如果使用 pipenv 或 poetry，它们会自动处理依赖树，但本课程为保持教学简洁，统一使用 requirements.txt + venv 方案。
4.5 环境验证脚本
完成环境搭建后，运行以下脚本验证所有组件就绪：
# check_env.py
import sys
import importlib
required_packages = [
("networkx", "3.0"),
("pandas", "2.0"),
("numpy", "1.24"),
("yaml", "6.0"),
("schedule", "1.0"),
("loguru", "0.7"),
]
print(f"Python 版本: {sys.version}")
print(f"虚拟环境路径: {sys.prefix}")
print("-" * 40)
all_ok = True
for pkg_name, min_ver in required_packages:
try:
mod = importlib.import_module(pkg_name)
ver = getattr(mod, "__version__", "unknown")
status = "✅" if ver >= min_ver else "⚠️"
print(f"{status} {pkg_name}: {ver} (需要 >= {min_ver})")
except ImportError:
print(f"❌ {pkg_name}: 未安装")
all_ok = False
print("-" * 40)
if all_ok:
print("✅ 环境检查通过，可以开始阈值巡检开发！")
else:
print("❌ 环境不完整，请检查缺失的依赖。")
执行方式：
python check_env.py
4.6 本章小结
- 使用 Python 3.10+，推荐 3.11 版本。
- 通过
python3 -m venv .venv创建隔离环境，激活后操作。 - 使用
pip freeze > requirements.txt锁定依赖，pip install -r requirements.txt复现环境。 - 生产项目可拆分
base/dev/ci多文件管理依赖。 - 运行
check_env.py验证环境完整性。