VeighNa（vn.py）PyCharm 开发指南：环境配置、Trader 启动与 C++ 回调断点调试实战

VeighNa（vn.py）PyCharm 开发指南：环境配置、Trader 启动与 C++ 回调断点调试实战

【免费下载链接】vnpy基于Python的开源量化交易平台开发框架项目地址: https://gitcode.com/gh_mirrors/vn/vnpy

PyCharm 是 JetBrains 推出的专业 Python IDE，内置代码补全、静态检查、断点调试、包管理等一整套开发工具链。本文以当前仓库的开源量化交易框架 VeighNa 为核心，完整讲解从 PyCharm 安装、绑定 VeighNa Studio 解释器、创建项目、浏览框架源码，到启动 VeighNa Trader、编写策略回测脚本并执行断点调试的完整流程，同时深入剖析 C++ 回调线程（CTP 行情接口、PySide 图形库）的断点调试方案。读者读完本文后，即可在 PyCharm 中搭建一套可直接运行的 VeighNa 开发调试环境。

本文内容基于 Windows 系统编写，但对于 Linux/Mac 系统大部分也都适用。涉及的可运行脚本、回测示例与框架源码均位于当前仓库中，可随时对照查阅。

开发环境准备

系统要求

VeighNa 适用的 Windows 系统包括：

• Windows 10/11
• Windows Server 2019/2022

其他版本的 Windows 系统安装时可能遇到各种依赖库问题，不推荐使用。

安装 VeighNa Studio

在 Windows 系统上使用 VeighNa，推荐安装官方推出的【VeighNa Studio】Python 发行版，尤其是初次接触 Python 开发的新手用户。

作为一站式的量化投研交易 Python 环境，VeighNa Studio 整合了：

• Python 3.10 64 位（Python 官网版本）
• VeighNa 框架本身和其他相关依赖库
• VeighNa Station（VeighNa 框架的图形化管理工具）

从官方渠道下载 VeighNa Studio 安装包后，双击进入安装向导，推荐使用默认设置点击【快速安装】即可完成安装，安装目录建议保持默认的C:\veighna_studio，其他 VeighNa 文档和教程中均使用该目录作为 VeighNa 安装目录进行讲解（详见 Windows 安装指南）。

对于已有较丰富编程经验或需要特定 Python 发行版（如 Anaconda）的用户，也可以采用手动安装方案：准备好 Python 3.10 64 位环境（注意必须是 64 位版本），下载本仓库源码后在install.bat所在目录执行一键安装脚本，再进入examples/veighna_trader目录用python run.py启动 VeighNa Trader。

安装 PyCharm

从 PyCharm 官网下载 PyCharm Community 安装包（Community 社区版即可满足本文全部开发需求），下载完成后双击安装包进入 PyCharm 安装向导：

1. 在 PyCharm Community Edition Setup 页面按需勾选安装选项，例如Create Desktop Shortcut（创建桌面快捷方式）、Add launcher dir to the PATH等；
2. 一路按默认设置完成安装，最终进入安装成功页面；
3. 若前面勾选了创建桌面快捷方式，桌面上会出现 PyCharm 图标，双击即可运行。

创建 VeighNa 开发项目

新建项目并绑定解释器

启动 PyCharm 后，在弹出的欢迎界面中点击【New Project】创建新项目：

1. 在弹出的新项目窗口中，首先选择存放项目的文件夹路径【Location】；
2. 勾选 Python 解释器选项中的【Previously configured interpreter】（使用系统中已经安装的 Python 环境）；
3. 点击右侧 Add Interpreter 下拉框中的【Add Local Interpreter】；
4. 在弹出的对话框左侧点击【System Interpreter】标签，在右侧下拉框中选择 VeighNa Studio 自带 Python 解释器所在的路径（即 VeighNa Studio 安装目录C:\veighna_studio下的 Python 可执行文件）；
5. 点击底部的【OK】按钮保存解释器配置，回到新项目窗口后点击右下方的【Create】按钮完成创建。

创建成功后，PyCharm 即会以 VeighNa Studio 的 Python 3.10 环境作为项目解释器，这意味着框架依赖（如 PySide、pyqtgraph、pandas 等）无需额外配置即可直接 import。

浏览框架源码与模块包

项目创建成功后，点击左上方【External Libraries】，即可看到项目中可以调用的外部库。展开 site_packages 文件夹往下滚动，就能找到 VeighNa Studio 中的vnpy 核心框架包以及vnpy_ 前缀的插件模块包（如 vnpy_ctp、vnpy_ctastrategy、vnpy_ctabacktester 等）。

通过点击对应包名可以查看每个包内的源码文件，例如本仓库的 vnpy/trader/engine.py 定义了主引擎 MainEngine，vnpy/trader/ui/init.py 导出了MainWindow与create_qapp等 UI 组件。在 PyCharm 中浏览这些源码时有两个高频技巧：

• 查看文档信息：把鼠标光标移到代码上方，会自动弹出对应代码的文档字符串（docstring）信息；
• 跳转到声明：按住 Ctrl 键的同时用鼠标左键点击代码，会跳转到该符号的声明部分（类定义、函数签名、变量定义等）。

Python 包版本管理

点击窗口右下角的【Python 3.10】按钮，会弹出【Settings】项目配置窗口，可以看到当前解释器环境下安装的包名称、本地版本号、最新版本号。带有升级符号（向上箭头）的包，说明当前版本不是最新版，点击升级符号即可自动升级。

请注意：由于 VeighNa 对于部分依赖库有严格的版本要求，不建议用户手动升级安装的包到最新版，否则可能出现版本冲突，导致框架无法正常加载运行。

运行 VeighNa Trader 程序

准备启动脚本 run.py

从本仓库获取 examples/veighna_trader/run.py 启动脚本文件，将其放置于你的项目文件夹下（或直接以本仓库为项目），即可在窗口左侧的项目导航栏中看到 run.py 文件。

该启动脚本的核心逻辑（对应 run.py 中的main()函数）如下：

def main(): """""" qapp = create_qapp() event_engine = EventEngine() main_engine = MainEngine(event_engine) main_engine.add_gateway(CtpGateway) # main_engine.add_gateway(CtptestGateway) # main_engine.add_gateway(MiniGateway) ... main_engine.add_app(CtaStrategyApp) main_engine.add_app(CtaBacktesterApp) # main_engine.add_app(SpreadTradingApp) ... main_window = MainWindow(main_engine, event_engine) main_window.showMaximized() qapp.exec()

脚本依次完成四件事：创建 Qt 应用对象、创建事件引擎（EventEngine）与主引擎（MainEngine）、向主引擎注册交易接口（Gateway）和应用模块（App）、创建并最大化显示 VeighNa Trader 主窗口后进入 Qt 事件循环。

run.py 中包含了较多启动加载项，例如以#注释掉的CtptestGateway、MiniGateway、SpreadTradingApp、RiskManagerApp等接口与模块。请根据自己所用的操作系统以及实际的交易需求修改调整：若需加载某个接口或模块，取消对应行前的注释符号即可。

关闭绿色波浪线提示

run.py 中大量接口与模块名采用英文命名，若部分代码下方出现绿色波浪线（这是 PyCharm 的英文词语拼写检查提示），可以点击项目名称左方的主菜单按钮：【File】→【Settings】→【Editor】→【Inspections】→【Proofreading】，取消【Typo】的勾选后点击【OK】确认，回到主窗口后绿色波浪线即会消失。

运行脚本

在 run.py 上点击鼠标右键，选择【Run 'run'】即可开始运行。此时界面底部的终端内容输出区域会显示程序运行时的打印信息（如 "加载VeighNa Trader运行环境"、"初始化主引擎"、"注册交易接口"、"注册应用模块" 等日志），与此同时 VeighNa Trader 的主窗口也会自动弹出显示。

回到 PyCharm，项目界面右上角已经有 run 脚本的运行记录了，后续直接点击三角形运行按钮即可再次运行该脚本，无需重复右键操作。

断点调试策略回测脚本

PyCharm 的断点调试功能十分强大，这里使用一个 VeighNa 的策略历史回测脚本来演示完整调试流程。

创建回测脚本

在左侧项目导航栏中点击鼠标右键，选择【New】→【File】，在弹出的对话框中创建backtest.py，然后编写一段策略回测代码（具体可参考本仓库的 examples/cta_backtesting/backtesting_demo.ipynb，其使用vnpy_ctastrategy.backtesting模块的BacktestingEngine引擎，通过set_parameters()配置合约、周期、时间段、手续费率、滑点、合约乘数、价格跳动与回测资金，再通过add_strategy()加载策略后执行回测）。

回测脚本主体大致如下：

from datetime import datetime from vnpy.trader.optimize import OptimizationSetting from vnpy_ctastrategy.backtesting import BacktestingEngine from vnpy_ctastrategy.strategies.atr_rsi_strategy import AtrRsiStrategy engine = BacktestingEngine() engine.set_parameters( vt_symbol="IF888.CFFEX", interval="1m", start=datetime(2019, 1, 1), end=datetime(2019, 4, 30), rate=0.3 / 10000, slippage=0.2, size=300, pricetick=0.2, capital=1_000_000, ) engine.add_strategy(AtrRsiStrategy, {})

运行回测前请确保数据库内已有足够的历史数据（可通过 VeighNa Trader 的 CTA 回测模块下载，或使用数据服务导入），否则回测引擎会输出"历史数据不足，回测终止"的提示。

启动调试

1. 在想要调试的代码行左侧点击，打上红色圆点断点（例如engine.set_parameters(...)调用处）；
2. 在 backtest.py 上点击鼠标右键选择【Debug 'backtest'】开始调试脚本；
3. 启动调试后，主界面底部出现 Debug 窗口，程序会暂停运行在第一个断点处：左侧显示线程信息，右侧显示当前上下文中的变量信息。

调试过程中的常用控制按钮：

• Resume Program（播放键）：继续运行调试，直到下一个断点处再次暂停。此时底部右侧监控窗口中，当前上下文中的变量会随程序推进发生变化，可借此观察策略参数、引擎状态在回测各阶段的取值；
• Step Into：进入函数的内部查看运行时的细节状态（例如进入set_parameters()内部逐行观察参数赋值）；
• Step Over：越过子函数（子函数会执行，但不进入其内部）；
• Step Out：跳出当前函数，查看外层调用栈的状态；
• Stop 'backtest'：直接停止当前程序的运行；
• Rerun 'backtest'：调试结束后重新运行调试。

项目界面右上角会记录 backtest.py 的运行记录，后续可以通过点击这里的按钮直接启动调试任务。

指定程序的运行目录

在 PyCharm 新建项目时，默认是在当前目录下运行程序。若需要指定程序运行的目录（例如 VeighNa 需要以运行时目录为工作目录读取.vntrader下的配置文件），可以点击项目界面右上角的【Edit】进入【Run/Debug Configurations】界面，修改程序启动时的目录【Working directory】为指定路径即可。

C++ 回调断点调试

问题背景

通常情况下，PyCharm 只能在 Python 解释器中启动的线程里进行代码断点调试。部分用户反馈：在 C++ 回调函数（如 CTP API 接口、PySide 图形库等）中打断点但无法起效。这是因为这些回调运行在 C++ 层面创建的线程中，Python 调试器默认无法介入。

针对这种情况，可以通过在代码中手动设置断点的方式，实现对非 Python 线程（即 C++ 线程）的断点调试。

编写网关测试脚本

在项目左侧导航栏中点击鼠标右键，选择【New】→【File】，创建gateway_test.py，添加一段脚本策略的代码（可参考本仓库的 examples/veighna_trader/demo_script.py，其通过vnpy_scripttrader的ScriptEngine引擎完成行情订阅、合约查询与轮询行情输出）。

然后按住 Ctrl 同时用鼠标左键点击代码中的CtpGateway，PyCharm 会跳转至ctp_gateway.py的源码中（该文件位于 VeighNa Studio 环境 site_packages 下的vnpy_ctp包内），在想要调试的回调函数内打上断点（注意不要打在函数定义的 def 那一行，而要打在函数体内部的语句行）。

回到gateway_test.py，点击鼠标右键选择【Debug 'gateway_test'】开始调试。此时可观察到并没有进入之前设定的断点——这正是 C++ 回调线程无法被 Python 调试器捕获的表现。

使用 pydevd 手动挂接调试器

终止调试后，找到之前在ctp_gateway.py中设定的断点处，在回调函数内的断点之前添加以下代码：

import pydevd pydevd.settrace(suspend=False, trace_only_current_thread=True)

请注意以下几点：

• pydevd是 PyCharm 自带的调试插件，没有安装在 Python 解释器所在的 Python 环境里，因此在普通 Python 代码中直接 import 会失败，只能在上述 C++ 回调场景中配合 PyCharm 的调试器使用；
• suspend参数设置为 True 之后，调试会在这一句代码运行完之后暂停，而不是停在断点处；示例代码中使用suspend=False，即挂接调试器但不立即暂停，随后程序继续执行到真实断点处暂停；
• trace_only_current_thread参数设置为 True 之后，调试过程中只会监控当前线程，避免调试器被其他线程的频繁运行干扰；
• 调试结束之后不要忘记删掉这段代码，否则运行时会报pydevd未安装的错误。

验证调试效果

再次运行调试gateway_test.py脚本（调试前请确保已通过load_json函数读取connect_ctp.json，并在对应的.vntrader文件夹的 json 文件中配置了 CTP 账户登录信息——load_json是 VeighNa 框架中读取运行时配置文件的工具函数，定义于 vnpy/trader/utility.py，若文件不存在会自动创建空配置）。

此时可以看到底部的调试窗口中开始输出相关信息，同时程序暂停在了之前设置的断点处：左侧显示线程信息（可以看到多了一个 Dummy 线程显示，即 C++ 侧回调触发的线程），右侧显示变量信息（可以看到回调函数的入参，如行情 Tick、委托回报等）。

通过这种方式，即可像调试普通 Python 代码一样，逐行观察 CTP 行情回调、报单回报回调等底层数据流的处理过程，这对于排查交易接口层面的问题（如行情字段异常、回报状态不匹配）非常有帮助。

与 VS Code 的对比

最后给出 PyCharm 与 VS Code 在 VeighNa 开发场景下的两点关键差异：

1. Python 环境配置粒度：在 PyCharm 中，每个项目都需要对 Python 环境进行配置（即前文【创建项目】一节的操作）；而在 VS Code 中，默认通过窗口右下角的 Python 解释器选择器来选择全局的 Python 环境（针对所有打开的文件），项目级别的环境隔离需要额外通过.vscode/settings.json等配置实现；
2. Jupyter 支持：PyCharm 的 Community 版仅对 Jupyter 提供了只读支持，需要 Professional 版才能编辑和运行 Notebook；VS Code 仅需安装功能插件，就可以使用和 Jupyter 相关的全部功能（包括读取、编辑、运行）。

如果用户的主要开发工作集中在策略研究与 Notebook 交互式分析上，VS Code 的门槛更低；如果需要完整的 Python 工程化开发体验（断点调试、重构、测试等），PyCharm 是更顺手的选择。两者均可与本文介绍的 VeighNa Studio 解释器无缝配合。

小结

本文从零开始完成了 PyCharm 与 VeighNa 开发环境的搭建：绑定 VeighNa Studio 自带的 Python 3.10 解释器创建项目、通过 External Libraries 浏览 vnpy 核心框架与 vnpy_ 前缀插件模块源码、运行 examples/veighna_trader/run.py 启动 VeighNa Trader、对 examples/cta_backtesting/backtesting_demo.ipynb 对应的回测脚本执行断点调试，并解决了 C++ 回调线程无法断点的痛点（通过pydevd.settrace手动挂接调试器）。

掌握上述流程后，即可在 PyCharm 中完成 VeighNa 的策略开发、回测调试与接口问题排查的日常闭环。更多环境与功能细节可继续参考仓库内的 Windows 安装指南、VeighNa Station 使用说明 与 CTA 回测模块文档。

【免费下载链接】vnpy基于Python的开源量化交易平台开发框架项目地址: https://gitcode.com/gh_mirrors/vn/vnpy