overtrue/pinyin 的 sentence() 默认分词查表，对未登录词和多音字无上下文感知，convert() 则逐字查表、不切分；推荐 permalink() 处理 URL，自定义词典补丁解决专有名词，调用前需 trim() 和空值判断。
overtrue/pinyin 能解决绝大多数中文转拼音需求，但不是所有场景都适合直接调用 sentence() 或 convert() —— 特别是遇到多音字、专有名词、标点混排或需要 URL 友好输出时，必须干预转换逻辑。
为什么 sentence() 有时拼音不准？
它默认走「分词 + 通用词典查表」流程，对未登录词（如人名「单钰」、地名「六安」）或上下文敏感的多音字（如「长」在「长大」和「长度」中读音不同）无感知。词典基于 mozillazg/pinyin-data，不带语义分析能力。
实操建议：
- 优先用
permalink()处理标题类文本，它会自动过滤标点、转小写、用短横线连接，适合生成 URL - 对人名/地名等固定组合，用
convert()配合自定义词典补丁：$pinyin->convert('六安', ['六安' => 'lù ān']) - 避免对整段含英文/数字/符号的混合文本直接调用
sentence()，先用正则提取纯汉字再处理
convert() 和 sentence() 的核心区别在哪？
convert() 是原子级转换：逐字查表，不切分、不联想，适合已知结构的短文本（如字段值、用户名）；sentence() 会尝试分词，再对每个词查拼音，更接近自然语言处理流程，但依赖词典覆盖度。
性能与兼容性影响：
- 纯字串（如「你好世界」）两者结果一致，
convert()略快 - 含常见词组（如「中华人民共和国」）时，
sentence()更可能输出「zhōng huá rén mín gòng hé guó」而非逐字拼错 - PHP 8.1+ 下两者均无兼容问题，但低于 7.4 的环境需确认安装的是
^5.0版本，旧版不支持 PHP 8
如何让拼音输出适配前端链接或文件名？
直接用 permalink() 最省事，但它默认去掉声调、转小写、用短横线分隔，且无法控制是否保留空格或下划线。
Discussion Composer
下载
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
如果需要更精细控制（比如生成 S3 key 或数据库 slug），推荐组合使用：
- 先调用
sentence($text, $style = \Overtrue\Pinyin\Pinyin::STYLE_NORMAL)得到无声调拼音 - 再用
preg_replace('/[^\w]+/', '-', $pinyin)替换非字母数字为短横线 - 最后
trim($result, '-')去首尾短横线
示例：$slug = preg_replace('/[^\w]+/', '-', Pinyin::sentence('测试！@#文件名2024')); // ceshi-wenjianming2024
安装后报 Class 'Overtrue\Pinyin\Pinyin' not found 怎么办？
这不是库本身问题，而是自动加载失效。Composer 安装后必须确保项目已引入 vendor/autoload.php。
检查点：
- 确认执行过
composer install或composer require overtrue/pinyin:^5.0，且vendor/overtrue/pinyin/目录存在 - 脚本开头是否有
require __DIR__ . '/vendor/autoload.php';？CLI 脚本容易漏掉这行 - Laravel 用户无需手动 require，但需确认
config/app.php中未误删Overtrue\Pinyin\PinyinServiceProvider::class（v5 已移除服务提供者，纯静态调用）
sentence()，它不会报错，但返回空字符串，后续逻辑可能静默失败。加一层 if (!is_string($text) || !trim($text)) { return ''; } 很有必要。 
