ruby标签不显示拼音，八成是缺失rb标签或结构错位；必须用<rb>显式包裹每个被注音字符，与<rt>一一紧邻，且<ruby>内不得省略<rb>，否则现代浏览器直接降级为平铺文本。
ruby标签不显示拼音，八成是缺失或结构错位
现代浏览器（Chrome 120+、Firefox 125+、Safari 17+）已严格要求显式 rb 标签作为基字容器。写成 <ruby>汉<rt>hàn</rt></ruby> 在 Firefox 和新版 Edge 中会直接降级为平铺文本“汉hàn”，不是 bug，是规范执行——rt 没有锚定的 rb，就失去语义和渲染依据。
必须确保每个字都包裹在独立 rb 内，且与对应 rt 紧邻：
-
<ruby><rb>重</rb><rt>chóng</rt></ruby><ruby><rb>庆</rb><rt>qìng</rt></ruby>✅ -
<ruby><rb>重庆</rb><rt>chóng qìng</rt></ruby>❌（多字共用rb，对齐不可控） -
<ruby>重庆<rt>chóng qìng</rt></ruby>❌（无rb，Firefox/Safari 不触发注音排版）
lang属性错误导致屏幕阅读器跳过
ruby 的语义激活依赖 <html lang="zh-CN"> 或 ja/ko 等东亚语言码。若设为 zh、en-US 或空值，Firefox/Safari 会把 rb 当普通内联元素、rt 当纯文本，屏幕阅读器直接跳过注音；Chrome 虽能渲染视觉效果，但语义链已断裂。
动态切换语言时，仅改 UI 文本不够，必须同步重置：
立即学习“前端免费学习笔记（深入）”；
document.documentElement.lang = "zh-CN";- 避免用
dir="rtl"包裹ruby块——它干扰基线计算，导致rt错位到左侧 - 检查 DOM 中
<html>的lang属性是否始终为有效东亚语言码，不能是zh或und
样式未重置引发裁剪、错位或换行脱节
rt 默认样式在各浏览器中差异极大：Firefox 默认缩放 50%，Safari 可能忽略 line-height，Chrome 在父容器 line-height: 1 下常截断顶部。不手动覆盖，就会出现拼音被压扁、上浮、或换行后“字在上、音在下”。
关键 CSS 必须显式声明：
-
ruby { display: ruby; line-height: 1.8; }（强制识别 + 预留基线空间） -
rt { font-size: 0.65em; line-height: 1.2; text-align: center; }（禁用浏览器默认缩放） - 混排数字/英文时，给整个注音片段外层加
class="ruby-group"并设.ruby-group { white-space: nowrap; }，否则<ruby><rb>第</rb><rt>dì</rt></ruby>123<ruby><rb>页</rb><rt>yè</rt></ruby>在窄屏可能断成三行
导出 PDF 或打印时
wkhtmltopdf、Puppeteer 和浏览器原生打印预览均未实现 CSS Ruby Layout Module。它们解析到 rt 标签时直接跳过，连 DOM 节点都不创建——这不是漏了 CSS，也不是没加 rb，而是底层渲染引擎压根没这个模块。
导出前必须用 JS 主动降级：
- 遍历所有
ruby元素，提取rb.textContent和rt.textContent - 拼成
汉(hàn)格式，用textContent替换原节点（别用innerHTML，避免 XSS 风险） - 保留原始
ruby结构在 DOM 中，仅在打印媒体查询中隐藏并显示降级文本
最易被忽略的是：rb 不是可选语法糖，而是现代浏览器渲染拼音的硬性前提；所有非汉字字符（包括数字、emoji、全角标点）都得参与结构包裹，否则整段注音链就断了。
