期货量化项目Git工作流实战：回测可复现与版本管理

见过太多做期货量化交易的人，策略“版本”就是一堆命名混乱的文件：策略_最终版_v7.py、策略_真正最终版_20260115.py、策略_别动这个版本.py。2026年，手里的策略从螺纹钢单边扩展到跨品种套利、股指日内，代码量上去了、一起开发的人也多了，如果没有一套严谨的版本控制机制，迟早要出大事：回测结果对不上代码、参数被同事覆盖、实盘模型跟仓库里的代码根本不是同一份。这篇文章就把我把Git工作流正式引入期货量化项目之后的完整方案展开聊聊，从仓库怎么搭、分支怎么管，到每一次回测结果如何绑定到某一个commit，全程都是这一年多实测下来的做法，不是纸上谈兵。

1. 期货量化项目为什么绕不开版本控制：三个教训换来的认知

很多人觉得版本控制就是“给代码存个档”，这想法放在普通开发项目里还能凑合，放在期货量化交易里就是埋雷。期货市场天然带杠杆、带保证金、带换月规则，策略代码里一个合约代码写错、一个参数表没对齐，可能直接造成真金白银的亏损。没有版本控制，你连“当前这套代码到底是哪来的”这个问题都回答不了。

1.1 回测结果对不上代码：比亏损更可怕的事

我之前踩过最深的坑，就是半年前跑出来一组非常好的螺纹钢跨期套利参数，当时只改了代码没打Tag。等三个月后想回去复盘，打开工作区一看，代码已经被后来七八次实验改得面目全非。我对着回测报告里那个漂亮的收益曲线，死活找不到当初生成它的那份代码和参数。

那一刻我才意识到：在量化交易里，回测结果不可复现，等于这次回测不存在。你可能在10个策略里筛出1个能实盘的，但如果不能精确知道它是用哪份代码、哪组参数、哪个数据切片筛出来的，那前面的99次实验也是白做，后续想优化更是无从谈起。

1.2 参数文件与合约换月：期货特有的版本变量

期货项目和纯股票策略相比，有一个非常特殊的变量：合约本身会变。螺纹钢主力合约每隔几个月就换月，股指期货有四个合约同时在交易，不同年份、不同月份的合约代码完全不一样。很多策略的“状态”不只存在于代码逻辑里，还存在于一份合约参数表里——哪个品种用哪个月合约、展期规则是什么、保证金比例按多少算、滑点费用怎么设置。

这些参数文件如果不纳入版本管理，代码是同一个commit，但策略行为可能因为参数文件被改过而发生巨大变化。到最后你会发现，出问题的时候，连排查范围都不知道从哪里开始。

1.3 实盘漂移：你知道现在线上跑的是哪份代码吗

量化团队做到后期，最容易被忽视的就是实盘代码和回测代码的漂移。回测环境里的代码不断迭代优化，实盘环境里跑的还是两个月前部署的那个版本。没有版本控制的强制约束，很多团队是靠“记得”在维护实盘代码，这是非常危险的状态。

把Git工作流搭好之后，我们做了一次最基础的规范：线上部署必须从某个固定Tag拉代码，部署完必须记录当前commit号。这个习惯救过我一次——后来有一次实盘信号异常，我们第一件事就是对比线上commit和仓库最新commit，发现有人手动在服务器上改了参数没有同步回来。五分钟定位问题，这在以前是不可想象的效率。

2. 仓库初始化与分层设计：先搭好地基再谈工作流

确定要用Git管代码之后，第一步不是急着建分支，而是把仓库结构和基础设施搭好。地基打不稳，后面天天都在处理大小写文件名冲突、大文件撑爆仓库、密钥泄露这些烂事。

2.1 Git安装与全局配置：一次配好，后面省心

环境安装本身不复杂，但有几个细节很容易被忽略。

• Windows下建议去Git官网下载安装包，或者用winget安装：winget install --id Git.Git -e --source winget，安装时勾选“Checkout as-is, commit as-is”，避免换行符自动转换带来的diff噪声。
• macOS直接用Homebrew：brew install git。
• Linux用系统包管理器就行：sudo apt install git。

装完之后，全局配置里有三项必须一次性配好：

bash复制git config --global user.name "your_username"
git config --global user.email "your_email@example.com"
git config --global init.defaultBranch main
git config --global core.autocrlf input

init.defaultBranch main是避免每次初始化仓库还默认建master分支，core.autocrlf input是告诉Git不要自作主张把换行符全部转成CRLF，否则在Windows和Linux之间切来切去的时候，git diff会莫名其妙多出一堆改动。

2.2 仓库目录结构：策略、数据、配置、文档四分离

量化项目的仓库结构，我推荐按职责分目录，把策略代码、配置文件、研究成果、脚本和文档彻底分开。这是我们跑了一年多的稳定结构：

text复制quant/
├── strategies/           # 策略代码
│   ├── single_leg/       # 单边趋势策略
│   ├── spread/           # 跨期套利策略
│   └── statarb/          # 统计套利策略
├── configs/              # 参数配置、合约表、风控参数
│   ├── production/       # 实盘使用的配置
│   └── research/         # 回测实验配置
├── research/             # 回测报告、研究笔记、结果存根
├── scripts/              # 数据下载、预处理、部署脚本
├── docs/                 # 设计文档、操作手册
├── requirements.txt
├── environment.yml
└── .gitignore

这套结构的好处是：当你看到一个回测报告，可以顺着目录快速定位对应策略代码和配置文件。策略代码里不写死任何具体合约和参数，全部从configs读取，改参数不用动逻辑，改逻辑不用碰参数，两者各自独立纳入版本管理。

2.3 .gitignore的禁区：密钥、大文件、缓存

.gitignore是整个仓库的“防火墙”，没写好它会让你后续付出惨痛代价。下面这个清单直接抄作业：

gitignore复制# Python缓存与构建目录
__pycache__/
*.py[cod]
build/
dist/

# 密钥与敏感信息
*.pem
*.key
.env
configs/secrets/

# 数据文件（体量大、易变，不入库）
data/
*.h5
*.parquet
*.csv

# 日志与回测输出
logs/
results/*.csv
results/*.png

# IDE与系统文件
.idea/
.vscode/
.DS_Store

有几个边界要解释清楚。data/目录整个排除，因为行情数据动辄几十GB，放Git里会造成灾难。results/目录只放代码不放输出文件，回测生成的图表和明细表全部落到本地，需要用的时候单独归档。

配置里的密钥文件是重点中的重点。很多期货柜台提供的API接口把access key放在配置文件里，一旦被提交进Git历史，就算后面删掉，历史记录里仍然可以翻出来。密钥这块，后面第5章会专门讲处理方案。

2.4 大文件怎么办：Git LFS与外部数据仓

有人可能会问：回测用的数据文件如果团队其他人也需要，怎么共享？答案不是硬塞进Git，而是分开管理。Git LFS可以解决“二进制文件进版本控制”的问题，但性价比不高。

我们的做法是：数据文件放专门的数据存储（比如NAS或对象存储），仓库里只保存一个data_manifest.json，记录每份数据的文件名、生成时间、来源和版本号。策略代码需要什么数据，按清单去取。这样既保证了数据变化可追溯，又避免了Git仓库被大文件拖垮。

如果确实有一些小体量的预处理数据需要跟着代码走，可以用Git LFS：

bash复制git lfs install
git lfs track "data/processed/*.parquet"
git add .gitattributes
git commit -m "chore: track processed parquet files with Git LFS"

但要记住，LFS不是免费午餐，拉取大文件同样耗时，能不用就不用。

3. 从策略实验到实盘部署：一套适合量化迭代的分支模型

分支策略是Git工作流里最容易被过度设计、也最容易被完全忽视的部分。量化项目和其他软件项目不太一样：我们既要快速迭代实验，又要保证实盘稳定，所以分支模型必须兼顾速度和可靠性。

3.1 三种主流分支策略选型：Git Flow、GitHub Flow、Trunk-based

先做一个快速对比：

量化团队的真实情况是：策略实验的频率非常高，但实盘上线又需要严格把关。纯Git Flow太重，每次都走develop、release、hotfix三套分支会很累；纯GitHub Flow又太松，实盘策略必须有明确的版本边界。

3.2 分支命名与职责划分：量化场景的定制方案

我最终采用的是一个基于Trunk-based、但保留Tag和短生命周期分支的混合模型。分支划分很精简：

分支命名是关键。我见过太多feature/new_strategy这种名字，一周之后就忘了这是哪个品种的策略。规范化之后我们统一用这种格式：

text复制feature/rb-spread-20260315
feature/if-daytrend-20260402
hotfix/position-calculation-error

rb-spread代表螺纹钢跨期套利，if-daytrend代表沪深300股指期货日内趋势，一眼就能看出分支在做什么。所有实验分支都从dev切出来，合并回dev之前必须保证该分支完整跑过至少一次回测。

3.3 提交规范：让git log变成策略变更日志

分支管好了，接下来要管的是commit。很多量化开发者的commit message是“update”“fix”这种两个字，三个月之后回头看log，完全不知道当时干了什么。我要求团队统一用一种简化版的Conventional Commit格式：

text复制<type>(<scope>): <subject>

[optional body: 回测结果、参数变化、验证情况]

type常用这几类：

• feat：新策略、新功能
• fix：修复逻辑错误
• perf：性能优化
• config：参数配置变更
• docs：文档更新
• chore：构建、依赖等杂项

scope写品种或模块，subject用一句动词短语说清楚。举例：

text复制fix(rb-spread): 修复换月时新旧合约并存的信号重复问题

换仓窗口从3天调整为2天，避免信号在主力合约切换期间重复触发。
回测: rb主力连续2023-2026，年化收益提升2.3%，最大回撤降低0.8%。

这种commit message的好处是，后续可以用一条命令快速浏览历史变更：

bash复制git log --oneline --graph --decorate -30

一眼看去就知道最近这段时间哪个品种在改什么、是修复还是新功能，检索效率高一大截。

4. 回测可复现：让每一次结果绑定一个commit

做量化最忌讳的就是“跑过一次，再也跑不回来”。不管是论文、内部报告还是跟合伙人汇报，每次回测结果都应该能够被精确重建。Git在这一环节扮演的角色，是把代码、配置、依赖、结果串成一条完整证据链。

4.1 Tag发布规范：打上可追溯的标记

分支解决的是“并行开发”的问题，Tag解决的是“版本快照”的问题。当一套策略经过回测、模拟、实盘验证之后，必须在main分支上打Tag。我们统一用这套格式：

text复制策略名-主版本.次版本.修订号
prod-品种-YYYYMMDD

实盘部署的Tag单独一套前缀，规则是prod-加品种和日期：

bash复制git tag -a prod-rb-spread-20260315 -m "螺纹钢跨期套利实盘部署 2026-03-15 15:30"
git push origin prod-rb-spread-20260315

-a表示创建附注Tag，会记录打Tag的人、时间和说明。轻量Tag不支持这些元信息，在需要严格追溯的场景里不推荐。

有了Tag之后，任何一次实盘部署都可以用一个简单命令拉出精确代码：

bash复制git checkout prod-rb-spread-20260315

这就是版本控制的“上帝视角”：线上跑的任何东西，都对应仓库里一个不可变的状态。

4.2 参数配置进入版本库：统一管理，随时diff

上一章提到参数和代码分开，这里要强调一个关键动作：所有参数文件都必须进Git。我们用的是YAML格式的配置文件，策略运行时从configs目录读取参数，举一个示例：

yaml复制# configs/research/rb-spread-20260315.yml
entry:
  price_diff_threshold: 18.5
  position_ratio: 0.6
exit:
  profit_stop: 35.0
  loss_stop: 22.0
  max_hold_bars: 120
rollover:
  switch_days: 2
  exclude_same_signal: true
cost:
  commission: 0.00023
  slippage: 0.5
  margin_rate: 0.10
contract:
  active_months: [1, 5, 10]

这份文件直接入库，即使不读代码，只看参数文件也能还原当时的策略状态。这个文件的新版本之间可以用git diff精确对比，比如：

bash复制git diff prod-rb-spread-20260315 -- configs/research/rb-spread-20260315.yml

能清楚看到这个Tag和当前dev分支之间，参数到底变了哪些，这对复查“为什么实盘表现和当初回测有差异”极其有用。

4.3 环境依赖锁定：requirements.txt与environment.yml缺一不可

如果算法依赖的第三方库版本没锁住，哪怕代码和参数都是同一个commit，换一台机器可能就跑不出同样结果。Python量化项目里，numpy、pandas、ta-lib这些库的版本升级经常造成细微行为差异。

我们要求每个项目根目录同时维护两份文件：

text复制# requirements.txt —— 直接锁定精确版本
numpy==1.24.3
pandas==2.0.1
ta-lib==0.4.28
matplotlib==3.7.1

# environment.yml —— 锁定conda包版本
name: quant
dependencies:
  - python=3.10
  - numpy=1.24.3
  - pandas=2.0.1

注意别用pip freeze > requirements.txt一键生成，这东西会把很多无关依赖也锁进来，到了别的环境经常出现冲突。更靠谱的做法是：先安装自己实际用到的包，每装一个就更新依赖清单，保证清单干净且可复现。

4.4 回测结果存根：结果文件和run脚本的固化

代码、参数、依赖都能复现之后，还差最后一步：把回测结果本身纳入管理。我们的做法不是把整个回测报表存Git，而是让回测脚本自动输出一份“存根”文件到research/目录下，记录关键元信息：

python复制# scripts/run_backtest.py 片段
import subprocess, hashlib, json

def collect_repo_meta():
    """收集当前仓库版本信息"""
    head = subprocess.check_output(["git", "rev-parse", "HEAD"]).decode().strip()
    branch = subprocess.check_output(["git", "rev-parse", "--abbrev-ref", "HEAD"]).decode().strip()
    # 获取是否有未提交的改动
    dirty = subprocess.check_output(["git", "status", "--porcelain"]).decode()
    return {
        "commit": head,
        "branch": branch,
        "dirty": bool(dirty.strip()),
        "config_sha": hashlib.sha256(open("configs/research/rb-spread-20260315.yml", "rb").read()).hexdigest()[:12]
    }

meta = collect_repo_meta()
with open("research/backtest_meta.json", "w") as f:
    json.dump(meta, f, indent=2)

这份backtest_meta.json和回测结果报表放在一起。以后任何人看到一份回测报表，打开这个JSON就知道它对应哪个commit、哪个分支和哪份配置。如果dirty字段是true，就说明回测时还有未提交改动，这份结果要打一个问号。这个设计简单但极其有效，我们靠它避免了很多次“假复现”。

5. 协作中的常见疑难：误提交密钥、大文件撑爆仓库、冲突处理

把Git工作流在团队里推行起来之后，一定会遇到几类高频问题。我把这一年多踩过的坑和止血方案整理在下面，每一个都是真实发生过的。

5.1 密钥被提交进历史怎么办

这是最尴尬也最紧迫的情况。有一天我发现某个.env文件被提交进了仓库，里面包含实盘账户API的access key。处理方法要分两步走：

第一步，立刻撤销该文件在当前版本的跟踪并添加忽略规则：

bash复制git rm --cached .env
echo ".env" >> .gitignore
git commit -m "chore: remove .env from repo"

但这一步只能让文件从最新版本消失，历史提交里依然存在。只要仓库是公开的，或者有其他人clone过，就必须把密钥当成已经泄露处理：去交易所/期货公司后台重新生成新的access key，而不是只删文件。

第二步，如果需要彻底清理历史记录里的文件，可以用git filter-repo（比filter-branch快得多）：

bash复制pip install git-filter-repo
git filter-repo --path .env --invert-paths
git push origin --force --all

注意：改写历史会让所有协作者的本地仓库和远程仓库失配。必须提前通知团队，重新clone或者硬重置本地分支。如果没有十足必要，不推荐对共享仓库做这类操作。

5.2 仓库越来越大的清理思路

量化仓库变胖，绝大多数原因是大文件误入历史。你以为在.gitignore里加了排除就万事大吉，但那些已经提交过的历史对象会一直躺在.git目录里。

先定位大文件的来源：

bash复制git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | awk '/^blob/ {print $NF, $3}' | sort -rn | head -20

找到是哪些文件之后，如果确认不需要保留历史，用git filter-repo的--strip-blobs-bigger-than参数一次性清理：

bash复制git filter-repo --strip-blobs-bigger-than 50M
git push origin --force --all

做过这类操作之后，还可以在远程仓库执行gc回收空间。更重要的是建立预防机制：超过50MB的文件直接进外部存储，只在仓库放引用。

5.3 Merge冲突与目录结构：设计阶段就能避开的坑

量化项目的merge冲突，大量集中在配置文件和模型参数文件上。几个同事同时在改同一个策略的参数，哪怕只是改了不同字段，Git也会因为上下文相近而产生冲突。

我们在实际中摸索出三条规则，极大减少了冲突频次：

• 每个策略的参数文件按品种-策略-日期拆分，低频共用的文件尽量分开存放，不要把几十个品种的参数塞进一个大文件里。
• 改参数前先git pull --rebase，把远端最新改动拉下来再动本地，能大幅降低冲突概率。
• 实验分支的生命周期控制在几天内，超过两周还不合并的feature分支，大概率会成为冲突源和废弃代码。宁可关闭重开，也不要一直挂在历史里看它腐烂。

关于git submodule，我的态度比较明确：量化项目不要轻易用submodule。子模块的指针漂移、版本不同步会让策略复现变成一个噩梦。如果公共代码需要复用，把它做成独立的Python包推到私有仓库，用requirements.txt指定版本号，比子模块干净十倍。

5.4 回滚实盘代码的正确姿势

实盘代码出问题的时候，第一反应是“马上回到旧版本”。但git reset和git revert用错，会直接毁掉团队工作区。

• git reset会移动分支指针，会改写历史，在共享分支上禁止使用。
• git revert会生成一个新的提交，把目标提交的改动反向回去，不改写历史，这才是共享分支回滚的正解。

实盘故障应急的流程应该是：

bash复制git checkout main
git log --oneline -5
git revert <bad_commit_hash>
git push origin main
git tag -a prod-rb-spread-20260315-hotfix -m "回滚：信号重复问题修复，恢复稳定版本"

revert新增的commit本身也会留下记录，这一点对审计特别重要。不要因为嫌日志“多了一个提交”就reset，在实盘系统里，可追溯永远比日志整洁更重要。

6. 实战心得：把版本控制变成团队的肌肉记忆

工具只是起点，真正让Git工作流发挥作用的是团队习惯。项目推进一年之后我最大的体会是：版本控制的价值不是“出问题的时候能用上”，而是它塑造了团队看待代码的方式。

6.1 从提交信息开始培养习惯

不用一上来就要求每个人都熟练所有Git高级命令。先在团队里立一条最基础、最不可妥协的规矩：每一个commit必须写清楚改了什么、为什么改。这条规矩的成本极低，但回报极高。我们当时是靠一次code review会议反思推行的——有个成员写了一个issue的修复，提交信息却是“update”，过后一周谁也记不清这个改动对应什么。从那天起，规范提交信息成了硬性要求。

后续再逐步推进分支规范、PR审查、Tag管理，每件事都先讲清楚“为什么”，再定“怎么做”。让团队理解这套流程是为了保护自己的成果和睡眠质量，而不是制造流程负担，推进阻力会小很多。

6.2 沉淀“版本审计”机制

2026年上半年，我们增加了一个季度一次的版本审计动作：由团队负责人和技术骨干一起，走一遍所有活跃策略的main分支Tag，核对每个实盘部署的commit是否都有对应Tag、回测存根文件是否完整、参数文件和策略代码是否匹配。

这个季度审计已经抓到了几个隐患：一个策略虽然在线上跑得正常，但回头发现它的回测存根文件没更新，实际线上的参数和当前仓库里的配置根本对不上；另一个策略的Tag只打到了commit上，没有加附注说明，导致后续查询时缺少部署人的信息。这些问题不带严重到直接亏钱，但都是潜在的雷。

6.3 自动化是扩展性的关键

团队从两个人扩展到五个人以后，纯手工维护版本秩序开始吃力。我们上了两样自动化：一是把CI配好，每次有人往main发起PR，自动跑一遍“从该分支拉代码 + 安装依赖 + 跑最小回测集”的流水线；二是部署脚本里强制带上git rev-parse输出，把部署时间、commit号、部署人写进日志文件。这两样加起来，基本堵住了最常见的疏漏。

再分享一个很小但极其实用的技巧：在终端配置里加一个显示当前分支的提示符——zsh用autoload -Uz vcs_info，bash用__git_ps1。这样每次切目录、敲命令都对当前分支一目了然，能避免大量“我明明改的是feat分支怎么跑出来的是main分支上面的行为”之类的低级错误。

Git工作流这套东西，真正落地之后并不复杂。仓库分好层、分支职责清晰、提交留痕、回测可复现、上线靠Tag，剩下的都是日常肌肉记忆。这些习惯会在某一次实盘异常、某一次策略回撤复盘、某一次需要向监管方说明“我们当时的代码做了什么”的时候，让你真切感受到当初付出的每一分钟都值了。