多音字和轻声必须人工判断并手动标注，不能依赖自动识别；“长”在“长度”中读cháng，在“长大”中读zhǎng；“重庆”整体标Chóngqìng，单字“重”需据语境选chóng或zhòng；轻声用无调字母（如ma、xi），非漏标声调；儿化音标huār、xiǎoháir，不拆ér；拼音标注直接影响语音朗读与无障碍访问，须人工校对。
多音字和轻声不能靠自动识别，必须人工判断后手动写对拼音；无调拼音（如“ma”）不是漏打声调，而是符合规范的轻声写法。
多音字必须按语境逐字定音，ruby 不会帮你选读音
浏览器和屏幕阅读器只认你写的拼音，不分析词义。“长”在“长度”里是 cháng，在“长大”里是 zhǎng，两个场景必须分别写两套 ruby 结构。常见错误是用一个通用拼音硬套所有情况，比如全标成 cháng，结果语音引擎朗读错、学生跟读错。
- 分词影响标注层级： “重庆”是专有名词，整体读
Chóngqìng，应写成<ruby>重庆<rt>Chóngqìng</rt></ruby> - 但“重”单独出现时，得按实际语境选
chóng或zhòng，不能复用词级拼音 - 变调字（如“一”“不”）也需人工处理：“一个”标
yí gè，“不一定”标bù yī dìng，不能写成yī或bù
轻声必须用无调字母，不是忘记加声调
轻声是独立声调类别，国际标准写法就是不带声调符号。比如“妈妈”的第二个“妈”标 ma，不是 mā 或 ma̱；“东西”的“西”标 xi，不是 xī。用带调字母反而是错的，可能被语音引擎误读为第一声。
- 输入方法：搜狗/讯飞等中文输入法开启软键盘 → 选“拼音字母”，直接敲
ma、xi即可输出无调字符 - 不要用删除声调符号的方式“凑”轻声——比如先打
mā再删掉ā上的横，容易残留控制符或编码异常 - CSS 中避免给
rt强制统一字体，某些字体对无调字母渲染偏移，建议用系统默认字体保真
儿化音只标 r，不拆成两个音节
“花儿”标 huār，不是 huā ér；“小孩儿”标 xiǎoháir，不是 xiǎo hái ér。这是汉语拼音正词法基本规则，ruby 只负责呈现，但你填进去的内容必须合规。
立即学习“前端免费学习笔记（深入）”；
- 儿化是音变，不是加字，“儿”的独立音节
ér在儿化词里不发音 - 如果把
ér单独塞进rt，会导致屏幕阅读器真读出“儿”，破坏语义 - 注意区分：带“儿”但不儿化的词（如“婴儿”）仍标
yīng'ér，中间加隔音符，这时才需要两个音节
最易被忽略的是：拼音标注不是排版装饰，它直接影响语音朗读、无障碍访问和搜索引擎理解。哪怕只错一个轻声，AT（辅助技术）就可能把整句语义读歪。别指望库或插件全自动——它们最多提供候选，最终决定权和校对责任一定在人手上。
