写了一大堆.py文件换个电脑就跑不通配置文件写死在代码里改个参数要翻三页别人接手你的项目三天没看懂目录结构。本篇给你一个「拿到就能用」的量化项目骨架含目录规范、配置分离、CLI 入口、环境自检。一、为什么需要「项目骨架」个人研究阶段一个main.py解决所有问题。但当你想换台机器复现回测结果让同事协作开发策略把脚本部署到服务器自动跑三个月后再回来看自己的代码就必须有统一的目录结构、配置管理、依赖清单、启动方式。否则每次迁移都是灾难。二、本文你将得到什么标准目录结构data / config / logs / strategies 各司其职配置与代码分离JSON 配置外置改参数不动代码CLI 一键入口python main.py init生成骨架python main.py run执行流水线环境自检脚本启动前自动检查 Python 版本和依赖包三、标准目录结构推荐的最小可运行结构my_quant_project/ ├── config/ │ ├── settings.json # 业务配置标的、数据源、风控阈值 │ └── logging.json # 日志配置 ├── data/ │ ├── raw/ # 原始 K 线从 API 拉取的 │ └── processed/ # 清洗后数据因子、信号 ├── logs/ # 运行时日志 ├── strategies/ # 策略脚本 ├── requirements.txt # 依赖清单 ├── .gitignore └── README.md设计原则config/与代码分离改参数不动 Pythondata/raw/与data/processed/分离原始数据不可覆盖加工数据可重新生成logs/独立策略跑了一个月日志文件可能上 GB单独目录方便清理和备份requirements.txt必须存在没有它换台机器就是「 import 地狱」四、CLI 入口三个命令搞定全部操作用 argparse 做子命令入口比一堆独立脚本好维护importargparseimportjsonimportos# 项目骨架模板SCAFFOLD{dirs:[data/raw,data/processed,logs,strategies,config],files:{config/settings.json:{data_source:mairui_api,stocks:[600519,000001,300750],risk_limits:{max_drawdown:-0.05,position_pct:0.8},},requirements.txt:mairui\npandas\nnumpy\nAPScheduler\n,.gitignore:__pycache__/\n*.pyc\n.env\nlogs/\n,README.md:# 量化系统\n\n## 启动\nbash\npython main.py run --config config/settings.json\n\n,},}defensure_project(rootmy_quant_project):fordinSCAFFOLD[dirs]:os.makedirs(os.path.join(root,d),exist_okTrue)forfname,contentinSCAFFOLD[files].items():pathos.path.join(root,fname)os.makedirs(os.path.dirname(path),exist_okTrue)textjson.dumps(content,indent2)ifisinstance(content,dict)elsecontentwithopen(path,w,encodingutf-8)asf:f.write(text)print(f[ok] 项目初始化完成:{root})defcheck_env():importsys py_oksys.version_info(3,9)print(fPython{sys.version.split()[0]}:{✅ifpy_okelse❌})forpkgin[mairui,pandas,numpy]:try:__import__(pkg)print(f{pkg}: ✅)exceptImportError:print(f{pkg}: ❌ (pip install{pkg}))returnpy_okdefrun_pipeline(config_path):withopen(config_path,r,encodingutf-8)asf:cfgjson.load(f)print(f数据源:{cfg[data_source]})print(f监控标的:{cfg[stocks]})forcodeincfg[stocks]:print(f[{code}] 拉取... 校验... PASS)print(f[ok] 流水线完成共处理{len(cfg[stocks])}只标的)命令注册parserargparse.ArgumentParser(description量化系统)subparser.add_subparsers(destcmd)sub.add_parser(init,help初始化项目骨架).add_argument(--name,defaultmy_quant_project)sub.add_parser(env,help环境自检)run_psub.add_parser(run,help运行流水线)run_p.add_argument(--config,defaultconfig/settings.json)argsparser.parse_args()ifargs.cmdinit:ensure_project(args.name)elifargs.cmdenv:check_env()elifargs.cmdrun:run_pipeline(args.config)实测运行$ python main.py init--namemy_quant_project[ok]项目初始化完成: my_quant_project $ python main.pyenvPython3.9.22: ✅ mairui: ✅ pandas: ✅ numpy: ✅ $ python main.py run--configmy_quant_project/config/settings.json 数据源: mairui_api 监控标的:[600519,000001,300750][600519]拉取... 校验... PASS[000001]拉取... 校验... PASS[300750]拉取... 校验... PASS[ok]流水线完成共处理3只标的五、配置分离JSON 外置 环境变量兜底业务配置放config/settings.json{data_source:mairui_api,licence_env:MAIRUI_LICENCE,stocks:[600519,000001,300750],schedule:{hour:15,minute:35},risk_limits:{max_drawdown:-0.05,position_pct:0.8}}证书路径走环境变量不硬编码importos licenceos.environ.get(MAIRUI_LICENCE,)ifnotlicence:raiseRuntimeError(请设置环境变量 MAIRUI_LICENCE)好处敏感信息证书不进 Git不同环境开发/测试/生产用不同的环境变量同一套代码到处跑配置文件可版本化证书由运维单独管理六、常见坑.gitignore漏掉日志和数据logs/和data/raw/*.csv一定要写进.gitignore否则 Git 仓库会膨胀到几百 MB。requirements.txt 不写版本号生产环境建议写pandas2.2.3否则下次安装可能拿到不兼容的新版本。路径用硬编码的\\Windows 下\\在 Linux 上跑不通。统一用pathlib.Path或os.path.join。忽略日志轮转长期运行的系统logs/app.log会无限增长。生产环境建议用logging.handlers.RotatingFileHandler。七、小结本文给了一个「拿到就能用」的量化项目骨架目录结构data / config / logs / strategies 分离职责清晰CLI 入口init / env / run 三个命令覆盖日常操作配置分离业务参数 JSON 外置证书走环境变量环境自检启动前自动检查 Python 版本和依赖失败即停下一篇#07我们将解决「历史数据补采与回填」——断网、API 超时、新上市股票导致的数据缺口怎么用断点续传 幂等写入补回来免责声明本文仅供技术学习交流不构成任何投资建议。量化策略回测表现不代表未来收益投资有风险决策需谨慎。代码与文档https://github.com/MaiRuiApi