标注多音字必须逐字包裹并配，TTS需按平台规范用数字声调或特殊标记，姓氏读音须查权威字典并建统一映射表。
用 <ruby></ruby> 标多音字必须分字包裹，不能偷懒合包
很多人写 <ruby>单雄信<rt>shàn xióng xìn</rt></ruby>，结果拼音全堆在“单”字上方或错位显示——<ruby></ruby> 不是段落级容器，它只对紧邻的基字生效。正确做法是每个汉字单独套一层 <ruby></ruby>，拼音也按字拆开：
<ruby>单<rp>( </rp><rt>shàn</rt><rp> )</rp></ruby><ruby>雄<rp>( </rp><rt>xióng</rt><rp> )</rp></ruby><ruby>信<rp>( </rp><rt>xìn</rt><rp> )</rp></ruby>
漏掉 <rp></rp> 在旧浏览器（如 IE11、部分安卓 WebView）里会直接裸露拼音；用了全角空格或中文括号，会导致 <rt></rt> 内容被截断或排版崩坏。
pinyin-pro 的 mode: 'surname' 能自动识别常见姓氏读音
前端渲染前用 JS 预处理人名拼音，比硬编码更可持续。比如“曾小贤”中的“曾”，普通模式输出 céng，但加了姓氏模式就变成 zēng：
import { pinyin } from 'pinyin-pro';<br>const name = '曾小贤';<br>const surnamePinyin = pinyin(name, { mode: 'surname' }); // → 'zēng xiǎo xián'
这个模式依赖内置百家姓表，覆盖《百家姓》前 40 名中 9 个高频姓（如王、华、陶、柏），但对“万俟”“尉迟”这类复姓不生效——它们得手动进词典或用拼音标注法兜底。
立即学习“前端免费学习笔记（深入）”；
云声 Index-TTS 和讯飞智作等 TTS 系统需用拼音+数字强制锁定读音
HTML 渲染和语音合成是两套逻辑：<ruby></ruby> 只管显示，TTS 才决定怎么念。若不干预，TTS 多数按常用音合成，“单雄信”大概率念成 dān xióng xìn。此时必须用平台指定的拼音标注法：
- Index-TTS：直接替换为
shan4 雄信（注意声调用数字，且shan4后要空格） - 讯飞智作：用注音标记
{单}{雄}{信}或拼音标记单#shan xiong xin（注意#后不带声调，且仅作用于前一个词） - 花生AI：支持上传发音词典，格式为纯文本每行
单 shàn，但必须启用「启用自定义发音词典」开关才生效
别指望 TTS 自动识别上下文——“乐陵”的“乐”在地名里读 lào，但模型没训练过这个语境，不标就是 lè。
姓氏多音字必须人工判断，没有银弹方案
“解”作姓氏读 xiè，作动词读 jiě；“查”姓读 zhā，查资料读 chá。这些无法靠规则穷举，更不能依赖浏览器或 TTS 的默认分词。真正可靠的路径是：
- 先确认该字是否在《新华字典》第7版“姓氏义项”列表中（如“王、华、陶、柏”都单独立项）
- 再查《汉语史稿》或公安部《姓名登记条例》附录的规范读音表
- 最后统一在项目里建立人名拼音映射表，供前端渲染和 TTS 标注共用
最易被忽略的是：同一个字在不同系统中标注格式不互通。讯飞的 # 标记在 Index-TTS 里会被当乱码，<ruby></ruby> 的 <rt></rt> 内容也不会被 TTS 解析。标注必须按目标平台要求重写，不能复制粘贴混用。
