官方文档已经是 v2,pip 不加 --pre 你装到的还是 1.x

9 月 15 日，NautilusTrader 切到 2.0.0rc5。GitHub 上这个仓库现在 29161 star，文档站点已经按 v2 写。于是很自然会有人把安装命令从记忆里敲出来：uv pip install nautilus_trader。

我在本机核了一遍这条路。不加 --pre，PyPI 解析到的最新稳定版仍是 1.231.0（2026-08-02 发布）。加了 --pre，解析器会去找 2.0.0rc5。这台机器是 Intel macOS、uname -m 返回 x86_64、CPython 3.12.13——PyPI 上 rc5 只有 macosx_11_0_arm64、manylinux 和 win_amd64，没有 darwin-x86_64 wheel。uv 于是回退源码包，maturin 在 pep517 构建阶段报错：依赖 arrow 的本地 patch src/patches/arrow-compat/Cargo.toml 不存在。

所以这篇文章不回答"v2 快不快"。它回答一个更窄的问题：你现在的系统，该不该从 1.231 迁到 rc5。

官方已经把主线切走了，但稳定版还停在 1.x

1.231.0 的 Release 写得很清楚：这是计划中的最后一版带 Cython v1 核心的 1.x。Rust + PyO3 的 v2 已经进入 RC，覆盖官方认为的支持工作流——Python 写策略、回测、实盘、风控成交、组合会计、catalog、现有适配器。更冷门的表面被放到 v2 roadmap #4042^[1]，不当作切版本的阻塞项。

文档的安装页把这个分裂写到了警告框里：当前文档覆盖 2.x；你若装到 1.x，示例会直接炸。他们举的报错不是假想的：

ImportError: cannot import name 'OrderSide' from 'nautilus_trader.model'ImportError: cannot import name 'BacktestEngine' from 'nautilus_trader.backtest'TypeError: Struct types cannot define __init__

对应的 import 已经换了模块路径。迁移指南 MIGRATION_V2.md 里最常见的几行：

• • nautilus_trader.backtest.engine.BacktestEngine -> nautilus_trader.backtest.BacktestEngine
• • nautilus_trader.live.node.TradingNode -> nautilus_trader.live.LiveNode
• • nautilus_trader.model.enums.OrderSide -> nautilus_trader.model.OrderSide

两个包的 import 名都叫 nautilus_trader。官方要求：分开两个虚拟环境，永远不要装进同一个。核验命令只有这一句：

python -c "import nautilus_trader; print(nautilus_trader.__version__)"

看到 1. 就是稳定线，看到 2. 才对得上现在的文档。官方给的 v2 安装是：

uv venv --python 3.14source .venv/bin/activateuv pip install --pre nautilus_trader

还有两句同样硬的话：不要在 Nautilus 源码仓库里跑这条命令（仓库的 exclude-newer 会把刚发布的 RC 滤掉）；也不要用 RC 去控制真实资金。

默认值改了，回测数字会自己漂

导入换路径是机械活。真正会让"我迁完对一下收益曲线"失真的，是默认值。

迁移指南里这三条，我建议打印出来贴在屏幕边上：

1. 1. PortfolioConfig.use_mark_prices 默认变成 true，v1 默认 false。不想用标记价，得显式关掉。
2. 2. 回测如果省略 default_leverage，保证金账户现在是 10x，现金账户 1x。想保住 v1 的无杠杆行为，写 default_leverage=Decimal(1)。
3. 3. Order.avg_px 和 Order.slippage 从 float 换成 decimal.Decimal。Decimal("0.70000") == 0.7 在 Python 里是 False。还用浮点字面量做断言或阈值，测试会无声失败。

Postgres 用户还有一次必须做的 schema 变更：order.avg_px / order.slippage 从 double precision 改成 NUMERIC，节点连上去发现旧列类型会直接拒绝启动。另外如果 AGGRESSOR_SIDE 枚举还是 BUYER/SELLER，要先改成 BUY/SELL。旧 catalog 缺 activation_price 和 OrderFilled.info 的，不能原地升级。

这些都不是"API 更现代了"的软文，是回测指纹和实盘对账会偏的地方。官方甚至提供了 scripts/benchmark-backtest-versions.py，用隔离的 v1.231.0 worktree 和 v2 wheel 对着跑，要求至少 3 个 session，并且比对 event/order/position/account 指纹。有回归预算的团队应该走这条，而不是肉眼看一张权益曲线。

自定义交易所适配器：rc5 不是你的切日

如果只用官方适配器，上面那些已经够你做迁移实验。一旦你有自己的 live adapter，故事就不一样了。

8 月 9 日，Issue #4694^[2] 里有人把生产 v1 系统往 v2 迁，要挂印度股指期权的自有 venue。他们在 Python 里找不到受支持的接缝：LiveNodeBuilder.add_data_client() 只接受编译进 _libnautilus 的工厂；add_plugin() 直接报 host-side plug-in support 不在这个仓库。维护者 Chris Sellers 8 月 10 日的回复没有含糊：

The Python v2 pre-release package currently has no supported out-of-tree adapter seam.Until that lands, 1.231.0 remains the supported path for your existing adapter use case.

他还补了一句容易被忽略的：关掉 v1 新功能开发，不等于 1.231.0 不能用，也不等于你必须在 v2 补上这个扩展点之前迁生产。

后续有进展。8 月 17 日他们完成了 Python 托管事件循环（LiveNode.run_async()）；9 月 13 日在 develop 落地了自定义 Python data/exec client 注册，nightly 文档也有了 python_adapters.md^[3]。但 9 月 15 日的 rc5 迁移指南 "Known limitations" 仍然写着：out-of-tree Python factory 还没有等价物，v1 那种 LiveDataClient 子类化尚未接上。

生产决策只能跟已发布的 wheel 和仍未改口的限制走，不能跟 nightly 文档的时态打赌。自定义适配器继续停在 1.231.0，是官方维护者写过的 supported path，不是保守癖。

源码构建也不是随手的退路。同一条 Issue 里，16GB 机器用 release profile 的 lto=fat 会在最终链接被 SIGKILL；改 CARGO_PROFILE_RELEASE_LTO=thin 才能过。维护者给的开发路径是 make build-debug，避开 release LTO。Intel Mac 则更干脆：官方支持矩阵写的是 macOS 15+ ARM64，PyPI 上 1.231.0 和 2.0.0rc5 都没有 darwin-x86_64 wheel。我这边的 sdist 构建失败，只说明"这条机器不是官方安装面"，不说明 ARM 机器也装不上。

现在怎么选

新项目、只用官方适配器：可以在隔离环境装 rc5 做迁移演习，不要接真实资金。已有 v1 策略、没有自定义 live adapter：先改导入和三个默认值，再用官方对比脚本对回测指纹。自定义 Python 适配器、Intel Mac、或生产实盘：继续 1.231.0。

可以按这张表走：

我的结论很窄：v2 作为主线已经成立，官方适配器用户现在做隔离迁移是合理的；但它还不是"所有 1.x 用户的切日"。文档走在 wheel 前面，wheel 又走在自定义适配器前面。pip 不加 --pre 你会装到 1.x——这不是陷阱文案，是 2026 年 9 月 20 日 PyPI 上仍能核对到的事实。

你现在卡住的是官方适配器的 API 改名，还是自定义 venue 根本挂不上去？评论区说一下场景，我下一篇可以按"只迁 BacktestEngine"拆一版最小 diff。