必须与成对出现，因浏览器仅识别完整嵌套结构（为容器、为注音内容）作为注音语义；单独使用任一标签将被降级为纯文本，导致拼音不显示或错位。
直接用 <ruby></ruby> 包汉字、<rt></rt> 放拼音，结构必须严格一对一——不是“词配音”，而是“字配音”，漏掉 <rt></rt> 或多字共用一个 <rt></rt> 就会渲染失败或语义丢失。
为什么 <ruby></ruby> 必须和 <rt></rt> 成对出现
浏览器只把完整嵌套结构识别为注音语义：<ruby></ruby> 是容器，<rt></rt> 是内容，缺一不可。单独写 <ruby>汉</ruby> 或 <rt>hàn</rt>汉，现代浏览器大多会忽略注音逻辑，降级为纯文本。
- 常见错误现象：拼音不显示、出现在基字后面、被截断、或整个
<rt></rt>变成普通小字 - 根本原因常是 DOM 结构断裂，比如在 CMS 富文本中被自动过滤了
<rt></rt>标签 - 验证方法：打开开发者工具，检查元素是否被渲染为
display: ruby（Chrome/Firefox）或display: -webkit-ruby（Safari）
多字怎么处理：必须逐字包裹，不能偷懒
「你好」不能写成 <ruby>你好<rt>nǐ hǎo</rt></ruby>，否则部分 Safari 和旧 WebView 会把拼音叠在「你好」整体上方，且屏幕阅读器无法分别朗读每个字的读音。
- 正确写法是
<ruby>你<rt>nǐ</rt></ruby><ruby>好<rt>hǎo</rt></ruby>，或更规范地用<rb></rb>显式分隔：<ruby><rb>你</rb><rt>nǐ</rt><rb>好</rb><rt>hǎo</rt></ruby> -
<rb></rb>不是可选的——它明确定义基字范围，在复杂排版（如竖排、行内换行）中能防止错位 - 避免用正则简单替换「所有汉字」加
<ruby></ruby>，遇到 emoji、全角标点、组合字符（如「ā」）可能破坏结构
拼音怎么填：格式、大小写、声调有硬约束
拼音必须用半角小写字母，推荐带 Unicode 声调符（如 hàn），而非数字标调（如 han4）。后者虽能显示，但语音合成器可能无法正确识别变调规则。
- 禁用全角空格、中文冒号、连字符（如
nǐ-hǎo或nǐ：hǎo），会导致<rt></rt>内容被截断或错位 - 多音字必须按语境手动指定，
pypinyin.lazy_pinyin()默认返回常用音，不会自动判断「重」在「重庆」中读chóng - 轻声、儿化音要写完整，如「我们」标为
wǒ men，不是wǒ mén；「一会儿」应拆为yí huì ér，三字三<rt></rt>
兼容性与样式控制的关键细节
现代浏览器（Chrome 110+、Firefox 115+、Safari 17+）已原生支持，但默认渲染差异大：Safari 对 <rt></rt> 缩放更激进（约 50%），Chrome 约 60%，Firefox 则依赖父级 font-size 继承。仅靠 font-size: 0.6em 不够稳定。
- 必须加内联样式：
<rt style="font-size: 0.6em; line-height: 1.2;"></rt>，避免外部 CSS 类冲突 - 禁用
line-height: 1或font-size: 0等全局设置，否则<rt></rt>可能被裁掉顶部 - 移动端 Safari 不支持
ruby-position: under，只认over（即默认上方），无需额外声明 - IE 完全不支持，若需兼容，得用
<span class="ruby-fallback">汉(hàn)</span>+ CSS 模拟，但语义和无障碍能力归零
最易被忽略的是 <rb></rb> 的显式使用和非汉字块的隔离处理——混排文本（如「第1章:Python入门」）里，数字、英文、标点必须跳过拼音生成，否则 <ruby></ruby> 结构会因空 <rt></rt> 或数量错位而崩坏。这不是语法问题，而是数据流断裂。
