PHP实现汉字转拼音_ChinesePinyin类库安装与使用【指南】-php教程-PHP中文网

overtrue/pinyin 是 php 汉字转拼音最稳、最轻、中文支持最全的方案，需 php ≥7.2、utf-8 输入，推荐单例复用实例并确认编码与需求场景。

php实现汉字转拼音_chinesepinyin类库安装与使用【指南】

直接说结论：PHP 里做汉字转拼音，overtrue/pinyin 是目前最稳、最轻、中文支持最全的方案，不用自己写正则或查表，也不用装扩展，Composer 一行就能跑起来。

常见报错是 Could not find package overtrue/pinyin 或 PHP 版本不兼容。这个库要求 PHP >= 7.2，且默认走 Packagist 官方源。国内用户容易卡在源或网络上：

确认 PHP 版本：php -v，低于 7.2 就别硬试，老系统建议升级或改用 duzun/pinyin（但后者维护已停滞）
换国内镜像源：composer config -g repo.packagist composer https://packagist.phpcomposer.com（注意：该镜像已停用，推荐改用 https://packagist.org + composer config -g repo.packagist composer https://packagist.laravel-china.org，或直接用阿里云源：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/）
如果项目启用了 minimum-stability: stable，而当前最新版是 v4.x 的 RC 版，加 --with-all-dependencies 或显式指定版本：composer require overtrue/pinyin:^4.0

toPinyin() 对非 UTF-8 字符串直接返回空数组，不是 bug，是设计使然。它不做自动编码转换，也不会帮你 trim 或过滤 HTML 标签。

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

确保输入字符串是 UTF-8 编码：mb_detect_encoding($str, ['UTF-8', 'GB2312', 'GBK'], true) === 'UTF-8'，否则先转码：mb_convert_encoding($str, 'UTF-8', 'GB2312')
含空格、换行、标点时，toPinyin() 默认只处理汉字，其他字符原样保留；如需纯拼音流，用 toPinyin($str, PINYIN_NO_TONE | PINYIN_KEEP_ENGLISH) 并配合 array_filter() 去空
多音字默认取常用读音，要强制指定读音得用 toSentence() + 自定义词典，或提前调用 setPhrases(['长沙' => 'zhǎng shā'])

每次 new Pinyin() 都会加载词典文件（约 300KB），初始化内部 Trie 树。在接口高频调用场景下，重复实例化会造成明显开销。

把实例作为类属性或容器单例管理，例如 Laravel 中绑定到 Service Container：$this->app->singleton(Pinyin::class, function () { return new Pinyin(); });
不用词典功能时（比如只转单字），可传空构造参数跳过加载：new Pinyin([])，但此时多音字和地名识别会失效
批量处理大量文本时，优先用 toWords() 分词后再转，比逐字调用 toPinyin() 更准也略快

真正难的不是装包或调函数，而是你得清楚自己要的是「带声调的分词结果」还是「无空格小写流」，要不要兼容生僻地名，以及输入是否真的 UTF-8 —— 这些不确认清楚，后面所有调试都在绕弯。