模組 00：環境安裝與第一次運行從零開始，30 分鐘內跑出你的第一個回測結果

這個模組會帶你安裝所有需要的工具，然後用一個最簡單的策略跑出第一個回測。不用寫任何策略邏輯，先確保你的環境跑得通。

一、需要安裝什麼？

flowchart LR
                        subgraph os["💻 作業系統"]
                        direction TB
                        linux["Linux (推薦)"]
                        mac["macOS"]
                        wsl["Windows WSL2"]
                        end

                        subgraph tools["🔧 工具鏈"]
                        direction TB
                        python["Python 3.12-3.14"]
                        uv["uv 套件管理器"]
                        end

                        subgraph nautilus["🐚 NautilusTrader"]
                        direction TB
                        pip_install["pip install"]
                        source["或從源碼編譯"]
                        end

                        os --> tools
                        tools --> nautilus

二、Step-by-Step 安裝

Step 1：確認 Python 版本

# 檢查 Python 版本（需要 3.12 或更高，最高支援 3.14）
python3 --version
# 輸出應為：Python 3.12.x 或 3.13.x

# 💡 為什麼需要 3.12+？
# NautilusTrader 官方支援 Python 3.12-3.14：
#   - PyO3 綁定需要 3.12+ 的穩定 ABI
#   - 更快的啟動速度（CPython 優化）
#   - 更好的錯誤訊息

# ❌ 如果用 Python 3.11 或更低版本：
#   pip install nautilus_trader
#   → ERROR: Requires-Python >=3.12

Step 2：安裝 NautilusTrader

# 方法一：用 pip（最簡單）
pip install -U nautilus_trader

# 方法二：用 uv（更快，推薦）
pip install uv
uv pip install nautilus_trader

# 💡 為什麼推薦 uv？
# uv 是 Rust 寫的 Python 套件管理器，速度比 pip 快 10-100 倍
# ❌ pip install nautilus_trader → 可能需要 2-5 分鐘
# ✅ uv pip install nautilus_trader → 通常 10-30 秒

Step 3：驗證安裝

# 在 Python 中驗證
import nautilus_trader
print(nautilus_trader.__version__)
# 應該輸出類似：1.208.0

# 驗證核心組件可用
from nautilus_trader.backtest.node import BacktestNode
from nautilus_trader.model.data import QuoteTick, Bar
from nautilus_trader.trading.strategy import Strategy
print("✅ 所有核心組件載入成功！")

# Ubuntu/Debian
sudo apt install python3.12-dev

# 如果遇到 Rust 相關錯誤（從源碼編譯時）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

三、第一個回測：Hello NautilusTrader

下面是一個最簡單的回測範例。它不做任何交易，只是證明你的環境能跑。

"""
你的第一個 NautilusTrader 回測 — Hello World
把這段代碼存為 hello_nautilus.py，然後用 python hello_nautilus.py 運行
"""
from nautilus_trader.backtest.engine import BacktestEngine
from nautilus_trader.backtest.engine import BacktestEngineConfig
from nautilus_trader.model.currencies import USD
from nautilus_trader.model.data import QuoteTick
from nautilus_trader.model.enums import AccountType, OmsType
from nautilus_trader.model.identifiers import Venue
from nautilus_trader.model.objects import Money
from nautilus_trader.trading.strategy import Strategy
from nautilus_trader.config import StrategyConfig


# ── 1. 定義一個「什麼都不做」的策略 ──────────────────────────
class DoNothingConfig(StrategyConfig, frozen=True):
    """最簡單的策略配置：什麼參數都沒有"""
    pass


class DoNothingStrategy(Strategy):
    """
    這個策略什麼都不做。
    它的唯一目的是證明你的環境能正常運行。
    """
    def __init__(self, config: DoNothingConfig):
        super().__init__(config)

    def on_start(self):
        self.log.info("🚀 策略啟動了！環境正常！")

    def on_stop(self):
        self.log.info("🛑 策略停止了。恭喜，你的第一個回測成功了！")


# ── 2. 配置回測引擎 ─────────────────────────────────────────
config = BacktestEngineConfig(
    logging_level="INFO",        # 顯示日誌（方便看到發生了什麼）
    logging_level_file=None,     # 不寫日誌文件
)

engine = BacktestEngine(config=config)

# ── 3. 添加交易場所 ──────────────────────────────────────────
SIM = Venue("SIM")  # 「SIM」是一個模擬交易所
engine.add_venue(
    venue=SIM,
    oms_type=OmsType.NETTING,    # 淨額結算（後面會詳細講）
    account_type=AccountType.MARGIN,  # 保證金帳戶
    base_currency=USD,           # 帳戶基礎貨幣
    starting_balances=[Money(100_000, USD)],  # 初始資金 10 萬美元
)

# ── 4. 添加策略 ──────────────────────────────────────────────
strategy = DoNothingStrategy(config=DoNothingConfig())
engine.add_strategy(strategy)

# ── 5. 運行！ ────────────────────────────────────────────────
engine.run()

# ── 6. 看結果 ────────────────────────────────────────────────
print("\n" + "="*60)
print("📊 回測結果")
print("="*60)
print(f"帳戶餘額: {engine.portfolio.balances()}")
print(f"總訂單數: {len(engine.cache.orders())}")
print(f"總成交數: {len(engine.cache.positions())}")
print("=" * 60)
print("✅ 恭喜！你的 NautilusTrader 環境正常運作！")

# 清理
engine.dispose()

INFO  DoNothingStrategy: 🚀 策略啟動了！環境正常！
INFO  DoNothingStrategy: 🛑 策略停止了。恭喜，你的第一個回測成功了！

============================================================
📊 回測結果
============================================================
帳戶餘額: {USD: Money(100000.00, USD)}
總訂單數: 0
總成交數: 0
============================================================
✅ 恭喜！你的 NautilusTrader 環境正常運作！

四、代碼逐行解析

剛才的代碼雖然是「什麼都不做」的策略，但它已經展示了 NautilusTrader 的核心運作模式：

flowchart LR
                        subgraph setup["⚙️ 配置階段"]
                        direction TB
                        config_engine["1. 配置引擎"]
                        add_venue["2. 添加交易場所"]
                        add_strategy["3. 添加策略"]
                        config_engine --> add_venue --> add_strategy
                        end

                        subgraph run["▶️ 運行階段"]
                        direction TB
                        init["引擎初始化所有組件"]
                        start["調用策略的 on_start()"]
                        process["處理數據事件"]
                        stop["調用策略的 on_stop()"]
                        init --> start --> process --> stop
                        end

                        subgraph result["📊 分析階段"]
                        direction TB
                        balance["查看帳戶餘額"]
                        orders["查看訂單"]
                        tearsheet["生成績效報表"]
                        end

                        setup --> run
                        run --> result

五、Python 生存指南

如果你是 Python 初學者，以下是 NautilusTrader 中最常遇到的 Python 語法。你不需要先學完整個 Python，只要懂以下 7 點就夠了：

class MyStrategy(Strategy):
    # 你的策略繼承自 Strategy
    # 這代表它自動擁有了 Strategy 的所有功能

def __init__(self, config):
    super().__init__(config)  # 先讓父類把該準備的都準備好
    self.my_var = 0           # 然後再定義你自己的變數

def on_start(self):
    self.log.info("...")      # 調用自己的日誌器
    self.count = 1            # 設置自己的計數器

def on_bar(self, bar: Bar):
    # IDE 現在知道 bar 有 open, high, low, close 屬性了
    print(bar.close)

class MyConfig(StrategyConfig, frozen=True):
    symbol: str = "BTC-USDT"
    # c = MyConfig(...)
    # c.symbol = "ETH"  # ❌ 報錯！無法修改

price = 100
self.log.info(f"當前價格是 {price}")  # 輸出: 當前價格是 100

from decimal import Decimal
qty = Decimal("0.1")  # ✅ 精確
# qty = Decimal(0.1)  # ❌ 危險！可能有浮點誤差

六、專案目錄結構

了解 NautilusTrader 的原始碼目錄結構可以幫助你在需要時找到正確的參數和邏輯。

nautilus_trader/
├── model/           # 💎 領域模型（價格、訂單、持倉、金融工具）
│   ├── orders/      #     9 種訂單類型
│   ├── instruments/ #     金融工具定義（股票、期貨、期權...）
│   ├── data.pyx     #     市場數據類型（QuoteTick, Bar...）
│   └── position.pyx #     持倉計算
│
├── trading/         # 🎯 策略相關
│   ├── strategy.pyx #     Strategy 基類（你繼承這個）
│   ├── trader.py    #     Trader 管理器
│   └── controller.py#     交易控制器
│
├── data/            # 📊 數據引擎
│   ├── engine.pyx   #     DataEngine 核心
│   └── aggregation.pyx # K 線聚合
│
├── execution/       # ⚙️ 執行引擎
├── risk/            # 🛡️ 風控引擎
├── cache/           # 💾 緩存系統
├── common/          # 🔧 通用組件（Actor, MessageBus, 日誌...）
│
├── backtest/        # 🔬 回測引擎
│   ├── engine.pyx   #     BacktestEngine 核心引擎
│   └── models/      #     FillModel, FeeModel, LatencyModel
│
├── live/            # 🚀 實盤引擎
│   ├── node.py      #     TradingNode
│   ├── reconciliation.py  # 訂單對帳
│   └── retry.py     #     自動重試
│
├── adapters/        # 🔌 15 個交易所適配器
├── indicators/      # 📈 內建技術指標
├── accounting/      # 💰 會計與保證金
├── analysis/        # 📋 績效分析 & Tearsheet
├── persistence/     # 💿 數據持久化（Parquet/Catalog）
├── serialization/   # 📦 序列化（Arrow/MsgPack）
├── system/          # ⚡ 系統核心（Kernel）
└── config/          # ⚙️ 所有配置類

七、互動練習

checks = {
    "nautilus_trader": True,
    "BacktestEngine": True,
    "Strategy": True,
    "QuoteTick": True,
}
try:
    import nautilus_trader
    from nautilus_trader.backtest.engine import BacktestEngine
    from nautilus_trader.trading.strategy import Strategy
    from nautilus_trader.model.data import QuoteTick
except ImportError as e:
    print(f"❌ 缺少: {e}")
else:
    for name in checks:
        print(f"  ✅ {name}")
    print(f"\n版本: {nautilus_trader.__version__}")

from nautilus_trader.backtest.engine import BacktestEngine
from nautilus_trader.model.currencies import USD

engine = BacktestEngine()  # 錯誤 1: ???
engine.add_venue(
    venue="SIM",             # 錯誤 2: ???
    oms_type="NETTING",      # 錯誤 3: ???
    account_type=AccountType.MARGIN,
    base_currency=USD,
    starting_balances=[100000],
)

八、本模組重點回顧