usd_cnh 汇率 ticker 选错导致数据源修复：CNH=X 返回 0 行 vs USDCNY=X 返回 67 行——yfinance ticker 差异与外汇数据源选择决策

凌晨两点，数据 pipeline 跑完了，我习惯性地 SELECT COUNT(*) 了一眼汇率表——0 行。

不是报错，不是超时，就是安安静静地空着。上游日志里 yfinance 那行 downloaded 0 rows 甚至没触发告警，因为代码里没写行数校验。

排查了大概四十分钟，最后定位到一个 ticker 字符串：CNH=X。换成 USDCNY=X 再跑，67 行，秒出。

一个 ticker 字符串引发的 40 分钟

先还原一下背景。我们有个每日汇率同步任务，从 yfinance 拉 USD/CNH 的历史收盘价，写入内部数据仓库。ticker 是我当初写代码时从某个博客抄的 CNH=X，跑了一年都没问题。

某天开始，yfinance 返回空。我第一反应是 Yahoo Finance 改了接口，查了一圈 issue 没找到相关讨论。第二反应是网络问题，手动 curl 了一下 API 端点，有响应。第三反应才是——ticker 本身可能不对了。

把 CNH=X 换成 USDCNY=X 试了一下，67 行数据，日期范围也对得上。问题解决了，但心里不踏实：这两个 ticker 到底是不是同一个东西？

yfinance 外汇 ticker 的命名规则

yfinance 拉外汇数据用的是 Yahoo Finance 的 ticker 格式，规则大致是：

• 基础货币 + 计价货币 + =X
• 比如 EURUSD=X 表示 EUR/USD
• USDCNY=X 表示 USD/CNY

看起来很简单，但问题出在”离岸”这个概念上。

USDCNY=X 对应的是在岸人民币（CNY），交易场所是中国大陆的外汇市场。而 CNH 是离岸人民币，主要在港交所、新加坡、伦敦等地交易。两者虽然都是人民币，但汇率走势会有细微差异，尤其在资本管制收紧或市场情绪波动时，CNY 和 CNH 的价差可以拉到 200-500 个基点。

所以严格来说，CNH=X 和 USDCNY=X 不是同一个货币对。我换成 USDCNY=X 其实是一种妥协——用在了岸汇率近似替代离岸汇率。

那 CNH=X 为什么返回 0 行？

这是最让人困惑的部分。CNH=X 这个 ticker 在 Yahoo Finance 的网页上确实存在，你手动搜 “CNH=X” 能看到报价。但通过 yfinance 的 yf.download('CNH=X') 拉历史数据，返回空 DataFrame。

我后来对比了几种情况：

• yf.download('CNH=X') → 0 行
• yf.download('USDCNY=X') → 67 行
• yf.Ticker('CNH=X').history(period='1mo') → 也是 0 行
• yf.Ticker('USDCNH=X') → 0 行（这个 ticker 在 Yahoo 上根本不存在）

看起来 Yahoo Finance 对离岸人民币的历史数据支持很弱。实时报价可能有，但历史 K 线数据要么缺失，要么被 yfinance 的解析逻辑吞掉了。yfinance 的底层是调 Yahoo 的 chart API，返回的 JSON 里 timestamp 字段为空时，pandas 就会构造一个空 DataFrame，不会报错。

这就是最坑的地方：静默失败。没有异常，没有 warning，就是空。如果你的 pipeline 没有行数校验，这个 bug 可以潜伏很久。

外汇数据源怎么选

这次踩坑之后，我整理了一下外汇数据源的选项，按”能不能稳定拉到历史数据”这个标准排了个序：

yfinance：免费，够用，但外汇 ticker 覆盖不全。在岸货币对（USDCNY=X、EURUSD=X 等主流对）没问题，离岸品种（CNH）基本拉不到历史数据。适合原型验证，不适合生产。

exchangerate.host / exchangerate-api.com：免费额度有限，历史数据需要付费。API 设计比 yfinance 友好，返回结构化 JSON，不会静默失败。

Frankfurter API（基于 ECB 参考汇率）：完全免费，每天一个快照，支持 30 种货币。没有分钟级数据，但日频够用。ECB 的参考汇率是官方发布的，数据质量有保障。

付费数据商（Bloomberg、Refinitiv、OANDA）：数据最全，CNY 和 CNH 都有，支持 tick 级。但成本摆在那里，个人项目或中小团队不太现实。

我们的场景是日频、内部风控用、对精度要求是”别差太多就行”，所以最终决策是：

1. 主数据源切到 Frankfurter API（ECB 参考汇率），每天拉一次
2. 保留 yfinance 作为 fallback，ticker 用 USDCNY=X（在岸）
3. 在 pipeline 里加了行数校验：如果当天数据为 0 行，直接告警，不静默跳过

几个可以带走的教训

静默失败比报错更危险。 yfinance 拉不到数据时不会抛异常，空 DataFrame 会顺着 pipeline 一路流到下游。任何外部数据拉取，都应该有”最小行数”校验，不满足就 fail fast。

免费数据源的”免费”是有代价的。 yfinance 本质是爬虫，Yahoo Finance 没有任何 SLA。数据格式变了、ticker 下线了、API 限流了，你都不会收到通知。生产环境至少要有备用数据源。

在岸和离岸不是同一个东西。 如果你的业务涉及离岸人民币（比如港股打新、跨境结算），用 CNY 替代 CNH 会有系统性偏差。虽然日常偏差很小，但极端行情下会放大。能拿到 CNH 数据就用 CNH，拿不到就在文档里明确标注”此处用 CNY 近似 CNH”。