第二章 开发环境搭建与依赖安装
本章目标：在本地机器上快速搭建符合 fast‑follow 模块编译与运行的完整开发环境，确保 Python、pip、虚拟环境及核心依赖（CMake、pybind11、GGML）就绪，为后续章节的模块配置与调试打下可复现的基础。
2.1 核心原理：为什么需要隔离的环境
fast‑follow 模块依赖特定版本的 Python 运行时、C++ 编译器、CMake 配置脚本以及底层推理库（如 GGML）。同一台机器上可能共存多个项目，若不隔离，极易出现版本冲突、符号链接错误或 ABI 不兼容。通过虚拟环境+系统级依赖分离，实现：
- 依赖隔离：每个项目的 pip 包独立安装，互不干扰。
- 版本锁定：通过
requirements.txt精确约束 Python 库版本。 - 快速重建：删除虚拟环境即可彻底清理，不影响全局 Python。
- 可移植性：相同环境配置可在 CI/CD 或队友机器上复现。
| 组件 | 最低版本 | 说明 |
|---|---|---|
| 操作系统 | Ubuntu 20.04 / macOS 12 / Windows 10 (WSL2) | 推荐 Linux 或 WSL2；macOS 需安装 Xcode Command Line Tools |
| Python | 3.8.0 | 建议使用 Python 3.10 以获得最佳兼容性 |
| pip | 21.0 | 旧版本可能无法正确解析 manylinux 轮子 |
| virtualenv | 20.0 | Python 3.8+ 自带 venv 模块，亦可使用 virtualenv |
| CMake | 3.18 | 用于编译 C++ 扩展，需支持 pybind11 |
| pybind11 | 2.10 | 由 requirements.txt 自动安装，亦可通过 pip 手动升级 |
2.2 配置步骤（命令行 + 代码片段）
Step 1 检查操作系统与基础工具
# Linux (Ubuntu/Debian)
uname -a
sudo apt update && sudo apt install -y build-essential cmake
# macOS (需安装 Xcode CLI)
xcode-select --install
brew install cmake
# Windows (WSL2 Ubuntu)
# 在 PowerShell 中执行 wsl --install -d Ubuntu，然后进入 WSL 执行 Linux 命令Step 2 安装或升级 Python 与 pip
python3 --version # 应 ≥3.8
pip3 --version # 应 ≥21.0
# 若无 pip 或版本过旧：
python3 -m ensurepip --upgrade
python3 -m pip install --upgrade pipStep 3 创建虚拟环境
# 使用 venv（推荐）
python3 -m venv fastfollow_env
# 使用 virtualenv（备选）
# pip install virtualenv
# virtualenv fastfollow_envStep 4 激活虚拟环境
# Linux / macOS / WSL
source fastfollow_env/bin/activate
# Windows CMD
fastfollow_env\Scripts\activate.bat
# Windows PowerShell
fastfollow_env\Scripts\Activate.ps1激活后终端提示符前应出现 (fastfollow_env)。
Step 5 安装项目核心依赖
创建 requirements.txt 文件（可从项目仓库获取），内容示例：
# requirements.txt
numpy==1.24.3
pybind11==2.10.4
cmake==3.26.4
ggml==0.2.1
fastfollow-core==1.0.0执行安装：
pip install -r requirements.txt
# 验证安装
pip list | grep -E "numpy|pybind11|cmake|ggml|fastfollow"Step 6 验证环境可用性
# 导入基础模块
python -c "import numpy; import pybind11; print('OK')"
# 测试 CMake 能找到 Python
cmake --find-package -DNAME=Python3 -DCOMPILER_ID=GNU
💡 最佳实践：每次进入项目前先执行
source fastfollow_env/bin/activate；为方便，可将 virtual env 路径加入 .bashrc 或使用 direnv 自动加载。
2.3 常见错误与解决方法
| 错误现象 | 原因 | 解决方法 |
|---|---|---|
pip: command not found | Python 未安装或 PATH 未包含 | 检查 python3 -m pip；将 ~/.local/bin 加入 PATH |
virtualenv: command not found | 未安装 virtualenv 或使用了 venv 却误用命令 | 使用 python3 -m venv；或 pip install virtualenv |
ImportError: No module named 'numpy' | 在激活环境前执行了脚本，或 requirements 未安装 | 确保 (fastfollow_env) 出现在终端提示符；重新 pip install -r requirements.txt |
Cmake could not find Python3 | CMake 版本过低或 Python 开发头文件未安装 | 安装 python3-dev（Linux）或 python3-devel（macOS）；升级 CMake ≥3.18 |
Permission denied 在 pip install 时 | 未激活虚拟环境，尝试写入系统目录 | 激活虚拟环境后再执行；或使用 --user 标记临时绕过 |
2.4 开发环境搭建流程（SVG 结构图）
2.5 验收检查清单
完成本章后，逐项核查以下条目，确保环境就绪：
- ✅ 操作系统为 Ubuntu 20.04+ / macOS 12+ / Windows WSL2
- ✅ 已安装 build-essential 及 CMake ≥3.18
- ✅
python3 --version输出 ≥3.8 - ✅
pip3 --version输出 ≥21.0 - ✅ 虚拟环境
fastfollow_env已创建 - ✅ 激活后终端提示符显示
(fastfollow_env) - ✅
pip list中包含 numpy、pybind11、ggml、fastfollow-core - ✅
python -c "import numpy; import pybind11"无报错 - ✅
cmake --version输出 ≥3.18
📌 验收指令：保存以下测试脚本为
test_env.py，在虚拟环境中执行 python test_env.py，若全部通过则环境搭建完成。
#!/usr/bin/env python3
# test_env.py — 快速验收环境
import sys, subprocess, importlib
def check(name, ver):
try:
m = importlib.import_module(name)
print(f"✅ {name} == {m.__version__}")
except:
print(f"❌ {name} 未安装或版本不符")
check('numpy', '1.24')
check('pybind11', '2.10')
check('cmake', '3.18')
print("python --version:", sys.version)