<ruby>渲染失败的主因是嵌套结构非法：必须直接包含文本节点和<rt>，禁止额外包裹标签；<rp>非必需但强烈推荐以保障兼容性；批量加拼音需按字切分并静态生成。
HTML 中的 <ruby> 标签不是 Ruby 编程语言，而是专用于东亚文字注音（如汉字上标假名、拼音）的语义化标签。用错场景或结构会导致渲染失败、屏幕阅读器误读，甚至被浏览器忽略。
为什么 <ruby> 渲染不出来？
最常见原因是嵌套结构不合法 —— <ruby> 必须直接包含一个文本节点（被注音字）和一个 <rt>（注音），且 <rt> 不能包裹在 <rp> 以外的其他标签里。浏览器对非法嵌套极其严格，哪怕多一层 <span> 都会让整个注音失效。
-
<ruby>汉<rt>hàn</rt></ruby>✅ 正确 -
<ruby><span>汉</span><rt>hàn</rt></ruby>❌ 渲染为纯文本“汉hàn”，无注音样式 -
<ruby>汉字<rt>hàn zì</rt></ruby>❌ 一个<rt>不能覆盖多个字，需拆成两个<ruby>
<rp> 是必须写的吗？
不是必须，但强烈建议写。它只在浏览器不支持 <ruby> 时显示括号，让注音内容仍可读。现代 Chrome/Firefox/Safari 都支持 <ruby>，但旧版 IE 或某些邮件客户端会忽略 <rt>，此时 <rp> 就是兜底方案。
- 推荐写法：
<ruby>漢<rp>(</rp><rt>かん</rt><rp>)</rp></ruby> - 不写
<rp>：老环境里可能只显示“漢かん”，没有括号分隔，语义模糊 -
<rp>内容不可为空，否则部分 Safari 版本会跳过整组注音
怎么批量给 HTML 中的汉字加拼音？
手动加效率低还易出错，推荐用脚本预处理。核心逻辑是：用正则匹配汉字（/[\u4e00-\u9fa5]/gu），调用拼音库（如 JavaScript 的 pinyin 包），再拼成 <ruby>字<rp>(</rp><rt>pi yin</rt><rp>)</rp></ruby> 结构。
立即学习“前端免费学习笔记（深入）”；
- 注意：拼音库返回的通常是连续字符串（如
"shìjiè"），需按字切分（"世界" → ["shì", "jiè"]），否则一个<rt>对应多个字会失效 - 避免在
<pre>、<code>或已含<ruby>的区域重复处理，防止嵌套污染 - 服务端渲染时，优先在构建阶段生成静态
<ruby>，而非靠前端 JS 动态插入 —— 否则搜索引擎和无障碍工具可能抓不到注音内容
真正难的不是写对标签，而是确保每个 <ruby> 单元都满足「一对一、无包裹、有兜底」三个硬约束；一旦漏掉 <rp> 或嵌套了 <em>，视觉上就彻底消失了，连开发者工具里都看不出报错。
