4. 本地环境搭建
在进入策略编写与回测之前，必须先把本地研究环境搭稳。LEAN 是 QuantConnect 开源的量化回测引擎，支持 C# 与 Python 两种策略语言。本地化运行的价值在于：数据不出本机、调试可断点、版本可管理、回测可复现。本章围绕四件事展开：安装 LEAN CLI、配置 Python 环境、初始化工作区、解析项目结构。完成本章后，你应当能在终端里用一条命令拉起一个可运行的回测项目，并清楚每个目录和文件的职责。
一、核心原理：LEAN CLI 到底做了什么
LEAN CLI 是一个命令行工具，本质上是 LEAN 引擎的“项目管家”。它并不替代引擎，而是负责三件事：第一，管理本地工作区（workspace），每个工作区是一个独立的 LEAN 运行根目录；第二，管理项目（project），每个项目对应一套策略代码与配置；第三，管理数据与依赖，包括拉取示例数据、构建 Docker 镜像、调用本地或云端回测。理解这一点很关键：CLI 是入口，引擎是执行体，Python 环境是策略的运行宿主。
LEAN 的本地运行通常依赖 Docker。CLI 会拉取 quantconnect/lean 镜像，把工作区目录挂载进容器，再在容器内执行回测。这样做的好处是环境隔离、跨平台一致；代价是首次拉取镜像较慢，且需要本机已安装 Docker Desktop 或 Docker Engine。若你选择不使用 Docker，也可以直接以源码方式运行引擎，但配置成本更高，不适合入门阶段。
D:/lean-workspace 或 ~/lean-workspace。路径中的空格和中文在 Docker 挂载时容易引发难以排查的报错。二、方法流程：从零到可运行项目
下面按顺序给出可复制的操作流程。假设你使用 Windows 或 macOS，已安装 Python 3.11 与 Docker。
- 安装 LEAN CLI。推荐用 pipx 或 pip 安装到独立环境，避免污染系统 Python。
- 验证安装。执行版本命令，确认 CLI 可用。
- 登录（可选）。若需拉取云端数据或推送项目，执行登录；纯本地回测可跳过。
- 初始化工作区。在目标目录执行
lean init，CLI 会生成标准目录骨架。 - 创建项目。用
lean project-create生成 Python 策略模板。 - 配置 Python 环境。在项目内创建虚拟环境并安装
lean与依赖。 - 运行回测。用
lean backtest验证链路是否打通。
# 1. 安装 LEAN CLI（推荐 pipx）
pipx install lean
# 2. 验证
lean --version
# 3. 登录（可选）
lean login
# 4. 初始化工作区
mkdir D:/lean-workspace
cd D:/lean-workspace
lean init
# 5. 创建 Python 项目
lean project-create MyFirstStrategy --language python
# 6. 进入项目并配置虚拟环境
cd MyFirstStrategy
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
# source .venv/bin/activate
pip install lean
# 7. 运行回测
lean backtest
执行 lean backtest 后，CLI 会检查 Docker 镜像、挂载工作区、编译并运行策略，最后在终端输出统计摘要，并在项目目录下生成结果文件。首次运行会拉取镜像，耗时较长；后续运行会显著加快。
三、项目结构解析：每个目录的职责
初始化完成后，工作区与项目会形成一套固定结构。理解这套结构，能让你在排查问题时快速定位：是数据问题、配置问题，还是代码问题。
| 路径 | 类型 | 职责说明 |
|---|---|---|
lean.json | 工作区配置 | 定义数据目录、插件、算法路径等全局设置 |
data/ | 数据目录 | 存放本地历史数据，按资产类别与分辨率分层 |
MyFirstStrategy/ | 项目根 | 单个策略项目的容器 |
main.py | 策略入口 | 定义 QCAlgorithm 子类与 Initialize 逻辑 |
config.json | 回测配置 | 指定回测起止时间、初始资金、数据分辨率 |
research.ipynb | 研究笔记本 | 用于探索性数据分析与因子验证 |
backtests/ | 输出目录 | 存放回测结果、日志与统计报告 |
.venv/ | 虚拟环境 | 隔离项目依赖，避免版本冲突 |
其中 config.json 是最容易被忽视却最影响结果的文件。它决定了回测的时间窗口与数据分辨率。若时间窗口超出本地数据范围，回测会报“数据缺失”而非直接失败，容易让人误判为代码错误。
{
"algorithm-language": "Python",
"parameters": {},
"description": "My first local backtest",
"start-date": "2023-01-01",
"end-date": "2023-12-31",
"cash-amount": 100000,
"resolution": "Daily"
}
四、案例与误区复盘
案例场景：某学员在 Windows 上执行 lean backtest 后长时间无输出，误以为卡死。实际原因是首次拉取 Docker 镜像，终端未显示进度。解决方式是先单独执行 docker pull quantconnect/lean:latest，观察拉取进度，再运行回测。
常见误区一：把 CLI 装进系统 Python。这会导致依赖冲突，尤其是 pandas、numpy 版本被覆盖。正确做法是用 pipx 或独立虚拟环境安装 CLI，项目内再建自己的 .venv。
常见误区二：忽略数据目录。LEAN 默认从 data/ 读取本地数据。若未准备数据，回测会尝试联网拉取或直接报错。建议先用 CLI 提供的示例数据跑通链路，再替换为自己的数据。
常见误区三：路径含空格或中文。Docker 挂载对路径敏感，含空格时可能被截断。统一使用英文、无空格的短路径，可避免大量隐性故障。
pip install lean 到全局 Python。一旦后续需要升级或降级依赖，全局环境很难回滚，且会影响其他项目。完成本章后，你应当具备一个可运行、可调试、可复现的本地 LEAN 环境。下一步的重点不再是“能不能跑”，而是“跑得对不对”——这取决于策略逻辑、数据质量与回测配置三者的匹配程度。把环境搭稳，后面的量化研究才有可靠的地基。