标签必须成对嵌套，正确用法是字音字音，禁止整段拼音塞入单个；需注意浏览器兼容、换行控制与拼音准确性三者妥协。
ruby 标签必须成对嵌套，不能单独使用 <rt></rt>
直接写 <rt>拼音</rt> 是无效的，浏览器会忽略或错乱渲染。必须用 <ruby></ruby> 包裹基础文字，再用 <rt></rt> 提供注音，且 <rt></rt> 必须紧跟在对应字符或字组之后。
常见错误是把整段拼音塞进一个 <rt></rt> 里，比如：
<ruby>你好<rt>nǐ hǎo</rt></ruby>
这会导致拼音整体贴在“你好”下方，而非逐字对齐。正确做法是分字或按词拆开：
<ruby>你<rt>nǐ</rt>好<rt>hǎo</rt></ruby>
- 每个
<rt></rt>应紧邻它所标注的文本节点（不能隔空格、换行或内联元素） - 中文分词影响可读性：如“中华人民共和国”宜按词切分（
<ruby>中华人民<rt>Zhōnghuá Rénmín</rt>共和国<rt>Gònghéguó</rt></ruby>），而非逐字 -
<rp></rp>是可选的兜底括号，仅在不支持<ruby></ruby>的老浏览器中显示（如<rp>(</rp><rt>xxx</rt><rp>)</rp>），现代项目通常省略
中文排版中 ruby 的 CSS 控制非常有限
浏览器对 <ruby></ruby> 的默认样式差异大：Chrome 基本可靠，Firefox 对 <rt></rt> 行高和垂直偏移处理较松散，Safari 在 flex 或 grid 容器里可能错位。无法用 font-size 直接缩放 <rt></rt> —— 它会随父级等比缩放，但基线对齐易漂移。
- 强制统一行为需重置：
ruby { line-height: 1; }+rt { font-size: .5em; vertical-align: text-top; } - 避免在
<ruby></ruby>外层设display: inline-block或transform: scale()，会破坏内置布局逻辑 - 若需居中对齐多字注音（如“北京”标“Běijīng”），必须用
<rb></rb>（已废弃）或改用<span></span>+ 定位——<ruby></ruby>本身不支持跨字合并注音
服务端生成 ruby 时，拼音库选择直接影响准确性
直接用 g2p 或简单规则库（如 ruby-pinyin）处理“重庆”会标成 “Chóngqìng”，但人工校对常写作 “Chóng Qìng”。自动标注无法覆盖多音字、轻声、儿化音等语境变体。
- Ruby on Rails 中可用
ruby_pinyingem，但需预处理：调用Pinyin.t("重庆", tone: true)得到字符串，再手动按字拆分插入<ruby></ruby> - Node.js 环境常用
pinyin库，注意启用heteronym: false避免返回数组 - 最稳妥方式是人工维护拼音映射表（JSON），尤其对专有名词、古诗文——自动标注出错时，
<ruby></ruby>结构本身无法降级提示，错误拼音会直接显示
移动端 Safari 对 ruby 的 line-break 支持不稳定
长段落含 <ruby></ruby> 时，iOS Safari 可能在换行点切断字与注音关联，出现拼音悬空或错行。这不是代码写错，而是渲染引擎限制。
- 避免在
<p></p>内连续堆砌多个<ruby></ruby>，改用<span class="ruby-group"></span>包裹小段（如每句或每词） - 加
white-space: nowrap到<ruby></ruby>上能阻止折行，但可能引发横向溢出，需配合overflow-wrap: break-word - 真正需要响应式断行时，只能放弃
<ruby></ruby>，改用<div> + 绝对定位模拟，牺牲语义化保效果 <p>注音这件事，结构上 <code><ruby></ruby>是标准解法，但实际落地时，拼音准确性、浏览器兼容、换行控制三者永远在互相妥协。别指望写完就跑通所有环境，至少要在 iOS 和 Android Chrome 上实测两遍。
