title: 从原版 Backtrader 迁移指南 description: 如何从原版 backtrader 迁移到这个增强版分支

从原版 Backtrader 迁移指南¶

本指南帮助您从原版 [backtrader](https://github.com/mementum/backtrader) 迁移到这个增强版分支。好消息是：您的现有代码无需任何修改即可正常工作，因为我们保持了 100% 的 API 兼容性。

变化概览¶

此分支在保持完全 API 兼容的同时，引入了重要的内部改进：

| 领域 | 原版 | 本分支 | 收益 |

|——|———-|———–|———|

|性能| 基准性能 |快 45%| 回测更快 |

|测试| 约 300 个测试 | 917+ 测试，50% 覆盖率 | 更可靠 |

|文档 | 基础 | 全面的双语文档 | 更好的学习资源 |

破坏性变更¶

无（100% 向后兼容）¶

您所有现有的 backtrader 代码都可以无需修改地运行。以下是不影响用户的内部变更：

内部变更（不影响用户）¶

元类移除：MetaBase、MetaLineRoot、MetaIndicator 等被 donew() 模式替代
初始化模式：使用显式 __new__ + __init__ 链替代元类魔法
参数访问：self.p 和 self.params 现在在 __init__ 期间设置，而不是元类 __call__

新增功能¶

1. CCXT 实盘交易支持¶

此分支包含生产级的加密货币交易功能：

# 新增：CCXT Store 用于实盘交易

import backtrader as bt

store = bt.stores.CCXTStore(
    exchange='binance',
    currency='USDT',
    config={
        'apiKey': 'your_api_key',
        'secret': 'your_secret',
        'enableRateLimit': True,
    }
)

# WebSocket 数据源（新增）

data = store.getdata(
    dataname='BTC/USDT',
    timeframe=bt.TimeFrame.Minutes,
    compression=1,
    use_websocket=True,  # 低延迟 WebSocket

)

# 带自动订单管理的 Broker

broker = store.getbroker(use_threaded_order_manager=True)

```bash
详情参见 [CCXT 实盘交易指南](../CCXT_LIVE_TRADING_GUIDE.md)。

### 2. CTP 期货支持（中国市场）

```python

# 新增：CTP Store 用于中国期货

store = bt.stores.CTPStore(
    broker_id='9999',
    investor_id='your_id',
    password='your_password',
    td_address='tcp://180.168.146.187:10130',
    md_address='tcp://180.168.146.187:10131',
)

```bash

### 3. 增强的性能模式

#### TS 模式（时间序列）

针对单资产策略优化，使用 pandas 向量化：

```python
cerebro = bt.Cerebro()
cerebro.run(ts_mode=True)  # 适合的策略加速 10-50 倍

```bash

#### CS 模式（横截面）

针对多资产投资组合策略优化：

```python
cerebro = bt.Cerebro()
cerebro.run(cs_mode=True)  # 高效的横截面信号

```bash

### 4. Plotly 交互式绘图

```python

# 新增：基于 Web 的交互式绘图

cerebro.plot(style='plotly')

```bash
支持：

- 在 10 万+ 数据点上缩放和平移
- 悬停查看详细信息
- 多子图
- 深色/浅色主题

## 迁移步骤

### 第 1 步：安装本分支

```bash

# 如果已安装原版 backtrader，先卸载

pip uninstall backtrader

# 安装此分支

cd /path/to/this/fork
pip install -e .

# 或者从 PyPI 安装（发布后）

# pip install backtrader-enhanced

```bash

### 第 2 步：测试现有代码

无需修改即可运行您的现有策略：

```bash

# 您的策略文件

python my_strategy.py

# 运行测试

pytest tests/ -v

```bash

- *预期结果**：一切与之前完全相同。

### 第 3 步：启用性能优化（可选）

确认兼容性后，启用优化：

#### 编译 Cython 扩展

```bash

# Unix/Mac

cd backtrader && python -W ignore compile_cython_numba_files.py && cd .. && pip install -U .

# Windows

cd backtrader; python -W ignore compile_cython_numba_files.py; cd ..; pip install -U .

```bash

#### 使用性能模式

```python

# 时间序列策略（单资产）

cerebro.run(ts_mode=True)

# 横截面策略（多资产）

cerebro.run(cs_mode=True)

```bash

### 第 4 步：迁移到实盘交易（可选）

如果您想从回测转向实盘交易：

```python

# 旧版：仅回测

cerebro = bt.Cerebro()
data = bt.feeds.CSVGeneric(dataname='backtest_data.csv')
cerebro.adddata(data)

# 新版：实盘交易

cerebro = bt.Cerebro()
store = bt.stores.CCXTStore(exchange='binance', ...)
data = store.getdata(dataname='BTC/USDT', use_websocket=True)
cerebro.adddata(data)
broker = store.getbroker()
cerebro.setbroker(broker)

```bash

## 迁移前后代码示例

### 示例 1：简单策略（无需更改）

- *之前（原版）**：

```python
import backtrader as bt

class MyStrategy(bt.Strategy):
    params = (('period', 20),)

    def __init__(self):
        self.sma = bt.indicators.SMA(self.data.close, period=self.p.period)

    def next(self):
        if self.data.close[0] > self.sma[0]:
            self.buy()

cerebro = bt.Cerebro()
cerebro.addstrategy(MyStrategy)
cerebro.run()

```bash

- *之后（本分支）**：完全相同 - 无需更改！

### 示例 2：添加实盘交易

- *之前（原版 - 仅回测）**：

```python
cerebro = bt.Cerebro()
data = bt.feeds.YahooFinanceData(dataname='AAPL', fromdate=datetime(...))
cerebro.adddata(data)
cerebro.run()

```bash

- *之后（本分支 - 实盘交易）**：

```python
store = bt.stores.CCXTStore(
    exchange='binance',
    config={'apiKey': KEY, 'secret': SECRET}
)
data = store.getdata(
    dataname='BTC/USDT',
    use_websocket=True  # 实时数据

)
broker = store.getbroker()

cerebro = bt.Cerebro()
cerebro.adddata(data)
cerebro.setbroker(broker)
cerebro.run()  # 现在进行实盘交易！

```bash

### 示例 3：性能优化

- *之前（原版）**：

```python
cerebro = bt.Cerebro()

# ... 设置 ...

cerebro.run()  # 标准执行

```bash

- *之后（本分支 - 已优化）**：

```python
cerebro = bt.Cerebro()

# ... 设置 ...

# 选项 1：时间序列模式（单资产加速 10-50 倍）

cerebro.run(ts_mode=True)

# 选项 2：横截面模式（投资组合高效）

cerebro.run(cs_mode=True)

# 选项 3：使用 once() 模式配合 Cython 编译

cerebro.run()  # 自动使用编译优化

```bash

## 常见迁移问题

### 问题 1：导入冲突

- *问题**：同时安装了原版 backtrader 和本分支。

- *解决方案**：

```bash
pip uninstall backtrader
pip install -e /path/to/this/fork

```bash

### 问题 2：Cython 编译失败

- *问题**：Cython 扩展未编译。

- *解决方案**：

```bash

# 先安装 Cython

pip install cython

# 编译扩展

cd backtrader
python -W ignore compile_cython_numba_files.py
cd ..
pip install -U .

```bash

### 问题 3：WebSocket 连接问题

- *问题**：CCXT WebSocket 无法连接。

- *解决方案**：

```python

# 检查 ccxtpro 是否安装

pip install ccxtpro

# 如果 WebSocket 不可用，系统会自动回退到 REST 轮询

data = store.getdata(
    dataname='BTC/USDT',
    use_websocket=False  # 禁用 WebSocket，使用 REST

)

```bash

### 问题 4：测试结果不同

- *问题**：指标值有轻微数值差异。

- *解决方案**：这是预期现象，由于浮点精度改进所致。数值应在原版结果的 1e-10 范围内。

## 功能对照表

| 功能 | 原版 | 本分支 | 备注 |

|---------|----------|-----------|-------|

| **核心回测**| 完整 | 完整 | 100% 兼容 |

|**指标**| 60+ | 60+ | 相同指标，执行更快 |

|**分析器**| 全部 | 全部 | 相同分析器 |

|**观察器**| 全部 | 全部 | 相同观察器 |

|**数据源**| CSV, Yahoo, Pandas 等 | 以上全部 + CCXT, CTP | 新增实盘交易数据源 |

|**经纪商**| 标准, IB | 以上全部 + CCXT, CTP | 新增实盘交易经纪商 |

|**绘图**| Matplotlib | Matplotlib + Plotly + Bokeh | 新增交互式绘图 |

|**优化**| 内置 | 内置 + TS/CS 模式 | 新增性能模式 |

|**文档**| 有限 | 全面的双语文档 | 新增指南和 API 参考 |

|**测试**| 约 300 个测试 | 917+ 测试 | 50% 代码覆盖率 |

## 性能改进

基于标准化基准测试：

| 场景 | 原版 | 本分支 | 改进 |

|----------|----------|-----------|-------------|

| 简单策略（1000 根 K 线） | 2.3s | 1.3s |**快 43%**|

| 复杂策略（10 个指标） | 15.2s | 8.5s |**快 44%**|

| 投资组合（10 个资产） | 45.8s | 25.1s |**快 45%**|

| TS 模式（向量化） | N/A | 1.5s |**快 10 倍**|

| 使用 Cython | N/A | 0.8s |**快 20 倍**|

## 更多资源

### 文档

- [快速入门教程](../user_guide/quickstart.md)
- [CCXT 实盘交易指南](../CCXT_LIVE_TRADING_GUIDE.md)
- [架构文档](../ARCHITECTURE.md)
- [API 参考](/api/)
- [项目状态](../PROJECT_STATUS.md)

### 社区与支持

- **问题反馈**：在 GitHub Issues 上报告 bug
- **讨论交流**：使用 GitHub Discussions 提问
- **贡献代码**：参见 [CONTRIBUTING.md](../../CONTRIBUTING.md)

### 测试

```bash

# 运行所有测试

pytest tests/ -v

# 运行特定测试类别

pytest tests/original_tests/ -v
pytest tests/new_functions/ -v

# 带覆盖率报告

pytest tests/ --cov=backtrader --cov-report=term-missing

```bash

## 成功迁移清单

- [ ] 卸载原版 backtrader
- [ ] 安装本分支 (`pip install -e .`)
- [ ] 运行现有测试验证兼容性
- [ ] （可选）编译 Cython 扩展
- [ ] （可选）启用 TS/CS 性能模式
- [ ] （可选）迁移到 CCXT 实盘交易
- [ ] （可选）尝试 Plotly 交互式绘图
- [ ] 如扩展功能，更新文档/注释

## 快速参考

### 关键命令

```bash

# 安装

pip install -e .

# 编译 Cython（获得最大性能）

cd backtrader && python -W ignore compile_cython_numba_files.py && cd .. && pip install -U .

# 运行测试

pytest tests/ -v

# 生成文档

make docs

# 格式化代码

make format

```bash

### 性能提示

1. **始终编译 Cython**用于生产环境

2.**使用 TS 模式**进行单资产时间序列策略
3.**使用 CS 模式**进行多资产投资组合策略
4.**启用 WebSocket**进行实盘交易（更低延迟）
5.**使用 exactbars**进行长期回测（内存优化）

### 实盘交易提示

1.**先从模拟交易开始**验证您的策略
2.**使用 ThreadedOrderManager**实现非阻塞订单更新
3.**启用限流**尊重交易所限制
4.**监控连接健康**使用 ConnectionManager 回调
5.**处理错误** 在 `notify_order()` 中实现稳健交易

- --

- *恭喜！** 您已准备好使用这个增强版 backtrader 分支。您的现有代码可以正常工作，并且现在可以访问强大的实盘交易和性能改进功能。