Ruby标签必须嵌套rb与rt才生效，单独使用rt无效；基文须用rb显式包裹，rb与rt须一一对应、顺序严格；多字需分组独立ruby，不可合并；声调用Unicode预组合字符；动态生成时须确保rb包裹；旧浏览器需rp降级。
ruby 标签必须嵌套 rb + rt 才能生效
单独写 <ruby>汉<rt>hàn</rt></ruby> 是无效的——浏览器会忽略 <rt>，或把拼音平铺在汉字后面。HTML 规范要求基文（汉字）必须显式包裹在 <rb> 里，且 <rb> 和 <rt> 必须一一对应、顺序严格。
正确结构只能是：
<ruby> <rb>汉</rb> <rt>hàn</rt> </ruby>
-
<rb>不可省略，不能用普通文本或<span>替代 - 多个字必须各自独立套一层
<ruby>，比如“中国”要写成两组，不是一组<rb>中国</rb><rt>zhōng guó</rt> - 如果中间插入换行、空格或块级标签（如
<div>），会中断语义关联，导致渲染失败
多音字和词组必须人工拆字标注
<ruby> 不识别上下文，不会自动选音。“长”在“长江”读 cháng，在“长辈”读 zhǎng，你填什么就显示什么。词组如“重庆”也不能靠一个 <rt> 覆盖两个字——否则拼音会挤在一起、声调错位、CSS 无法单独控制每个字的注音样式。
推荐做法：
立即学习“前端免费学习笔记（深入）”；
- 按字拆开：
<ruby><rb>重</rb><rt>chóng</rt></ruby><ruby><rb>庆</rb><rt>qìng</rt></ruby> - 声调用 Unicode 预组合字符（如
ā、ǚ），不要用组合符（ǘ），后者在部分字体/浏览器中渲染不稳定 - 避免把整句拼音塞进一个
<rt>，比如<rt>wo men dou shi you xiu de ren</rt>—— 这会导致语音合成工具（TTS）无法按字切分，朗读错误
动态生成拼音时容易漏掉 DOM 结构校验
用 JavaScript 拼接字符串生成 <ruby> 时，常见错误是直接拼 "<ruby>" + char + "<rt>" + pinyin + "</rt></ruby>"，结果产出的是 <ruby>汉<rt>hàn</rt></ruby> —— 缺少 <rb>，结构非法。
正确做法必须保证每个字都被 <rb> 包裹：
- 用模板字符串显式写出
<rb>${char}</rb> - 不要依赖拼音库自动补结构，例如
pinyin-pro的pinyin()只返回字符串，不生成 HTML - 输入法组合输入（如中文输入法打字过程中的“正在输入”状态）会触发
compositionstart/compositionend，需拦截，否则未完成的字会提前被标注
旧浏览器 fallback 要用 rp，但现代项目可省略
IE 全系、Android 4.3 WebView、Outlook Desktop 等完全不解析 <ruby>，它们会丢弃 <rt> 和 <rp>，但保留其中的文本内容。所以加 <rp>(</rp> 和 <rp>)</rp> 后，在降级场景下能变成“汉(hàn)”，比“汉hàn”可读性高。
不过当前（2026 年）主流环境已基本支持 <ruby>，是否加 <rp> 取决于目标用户：
- 面向教育类网站、政务系统等仍需兼容 IE 或老旧邮件客户端 → 加
<rp> - 纯现代 Web 应用（Chrome/Firefox/Safari 最新版 + iOS/Android 主流 WebView）→ 可省略，减少冗余标签
- 注意 Safari 对连续多个
<ruby>的行内间距处理异常，必要时用font-size: 0父容器 + 子元素重设字号微调
