ruby标签仅支持单字对单音标注，需严格遵循rb/rt配对结构，无法自动识别多音字、语境变调或动态注音，须人工校验读音并配合CSS修复兼容性问题。
ruby 标签不是万能注音工具，它只认语义结构
浏览器渲染 ruby 的前提是：每个 ruby 元素内必须有且仅有一个基字（纯文本或 rb），再配一个 rt。写成 <ruby>你好<rt>nǐ hǎo</rt></ruby> 看似省事，实则基字是两个字符，“nǐ”和“hǎo”无法对齐到“你”“好”各自位置——Safari 会缩放错乱，旧版 Edge 可能直接跳过 rt。
常见错误现象：
-
<rt>单独出现，没包在<ruby>里，被当成普通内联元素 - 用
<ruby><rb>汉</rb><rb>字</rb><rt>hàn</rt><rt>zì</rt></ruby>，rb多个、rt多个，语义不匹配 - 把声调符号（如 ˋ ˊ ˇ ˆ）漏掉或误用全角符号，导致字体 fallback 到方块
多音字、连读、轻声不能靠 ruby 自动处理
ruby 不解析汉字语义，也不执行语音规则。同一个“行”字，在“行动”里读 xíng，在“银行”里读 háng，标签不会判断上下文，更不会自动变调（如“一”在去声前读 yí）。
使用场景限制很明确：
立即学习“前端免费学习笔记（深入）”；
- 适合人工校对过的静态内容，比如教材生字表、辞典词条
- 不适合古诗全文自动注音、儿童识字 App 的实时朗读支持
- 屏幕阅读器多数跳过
rt，无障碍访问（ARIA）需额外加aria-label
若真要动态处理，得先用 pinyin-pro 或 pypinyin 在服务端/构建时生成带声调的拼音，再手动塞进 <rt> ——ruby 只负责“怎么摆”，不管“摆什么”。
iOS 和 Safari 对 ruby 的兼容性坑最多
Safari 渲染 ruby 时默认不缩放 rt，也不强制居中，甚至可能把多个连续 ruby 挤成一行后整体上移。这不是 bug，是规范允许浏览器自由实现；但结果就是你在 Chrome 看得好好的，到 iPhone 上拼音飘了。
必须写的 CSS 修复项：
-
ruby { display: ruby; }：强制 Safari 识别容器类型（Firefox/Chrome 也认） ruby rt { font-size: 0.7em; line-height: 1; text-align: center; }- 禁用
vertical-align: super：它会让rt相对于整行偏移，而非相对于基字 - 避免
ruby-align: center：老 Safari 对多字并列支持不稳定，逐字包裹 + 上述样式更可靠
日文假名比拼音更吃字体和编码
日文注音对环境更敏感：っ（促音）、ー（长音符）、ょ（小假名）这些字符在 UTF-8 编码下容易被 JS 字符串操作破坏，比如用 escape() 处理会导致 %E3%82%87 这类编码残留，最终渲染成方块。
关键点：
- HTML 必须声明
<meta charset="utf-8">，服务端响应头也要设Content-Type: text/html; charset=utf-8 - 字体必须覆盖 Unicode Bopomofo（U+3105–U+312F）和 Hiragana/Katakana 区（U+3040–U+309F / U+30A0–U+30FF）
-
rp标签在现代环境基本无用，iOS Safari 几乎不渲染括号，还可能干扰朗读顺序，直接省略 - “东京”不能写成
<ruby>東京<rt>とうきょう</rt></ruby>，得拆成<ruby>東<rt>とう</rt></ruby><ruby>京<rt>きょう</rt></ruby>才能对齐
真正麻烦的从来不是标签怎么写，而是每个字的读音得人工查证——“上野”读 うえの，“上杉”却读 じょうすぎ，ruby 不帮你记这个。
