PinYin4j汉字转拼音使用及踩坑

1、pinyin4j是啥

pinyin4j 是一个开源的 Java 汉字转拼音库，纯 Java 实现，无额外依赖，支持主流中文汉字转拼音、多音字处理、拼音大小写、声调转换等功能。

2、pinyin4j代码使用

1. 引入依赖

java 复制代码

<dependency>
    <groupId>com.belerweb</groupId>
    <artifactId>pinyin4j</artifactId>
    <version>2.5.1</version>
</dependency>

2. 核心工具类

封装好的通用工具类，包含最常用的 4 个功能：

汉字转全拼（带 / 不带声调）
汉字转首字母
多音字处理
特殊字符过滤

java 复制代码

import net.sourceforge.pinyin4j.PinyinHelper;
import net.sourceforge.pinyin4j.format.HanyuPinyinCaseType;
import net.sourceforge.pinyin4j.format.HanyuPinyinOutputFormat;
import net.sourceforge.pinyin4j.format.HanyuPinyinToneType;
import net.sourceforge.pinyin4j.format.HanyuPinyinVCharType;
import net.sourceforge.pinyin4j.format.exception.BadHanyuPinyinOutputFormatCombination;

/**
 * pinyin4j 汉字转拼音工具类
 */
public class PinyinUtils {

    /**
     * 初始化拼音格式化配置（全局复用，无需重复创建）
     */
    private static final HanyuPinyinOutputFormat PINYIN_FORMAT;

    static {
        PINYIN_FORMAT = new HanyuPinyinOutputFormat();
        // 1. 拼音大小写：LOWERCASE小写 / UPPERCASE大写
        PINYIN_FORMAT.setCaseType(HanyuPinyinCaseType.LOWERCASE);
        // 2. 声调格式：WITHOUT_TONE无声调 / WITH_TONE_NUMBER数字声调 / WITH_TONE_MARK符号声调
        PINYIN_FORMAT.setToneType(HanyuPinyinToneType.WITHOUT_TONE);
        // 3. 特殊拼音ü显示：WITH_U_UNICODE标准格式 / WITH_V用v代替
        PINYIN_FORMAT.setVCharType(HanyuPinyinVCharType.WITH_V);
    }

    /**
     * 【常用】汉字字符串转全拼（无声调、小写、无空格）
     * 例：中国 -> zhongguo
     */
    public static String toPinyin(String chinese) {
        if (chinese == null || chinese.trim().isEmpty()) {
            return "";
        }
        StringBuilder result = new StringBuilder();
        char[] chars = chinese.toCharArray();

        try {
            for (char c : chars) {
                // 判断是否为汉字
                if (String.valueOf(c).matches("[\\u4e00-\\u9fa5]")) {
                    // 获取拼音（多音字返回数组，默认取第一个）
                    String[] pinyins = PinyinHelper.toHanyuPinyinStringArray(c, PINYIN_FORMAT);
                    if (pinyins != null && pinyins.length > 0) {
                        result.append(pinyins[0]);
                    }
                } else {
                    // 非汉字直接保留（数字、字母、符号等）
                    result.append(c);
                }
            }
        } catch (BadHanyuPinyinOutputFormatCombination e) {
            e.printStackTrace();
        }
        return result.toString();
    }

    /**
     * 【常用】汉字字符串转首字母
     * 例：中国 -> zg
     */
    public static String toFirstLetter(String chinese) {
        if (chinese == null || chinese.trim().isEmpty()) {
            return "";
        }
        StringBuilder result = new StringBuilder();
        char[] chars = chinese.toCharArray();

        try {
            for (char c : chars) {
                if (String.valueOf(c).matches("[\\u4e00-\\u9fa5]")) {
                    String[] pinyins = PinyinHelper.toHanyuPinyinStringArray(c, PINYIN_FORMAT);
                    if (pinyins != null && pinyins.length > 0) {
                        // 取首字母
                        result.append(pinyins[0].charAt(0));
                    }
                } else {
                    result.append(c);
                }
            }
        } catch (BadHanyuPinyinOutputFormatCombination e) {
            e.printStackTrace();
        }
        return result.toString();
    }

    /**
     * 获取汉字所有拼音（处理多音字）
     * 例：行 -> [xing, hang]
     */
    public static String[] getMultiPinyin(char c) {
        try {
            return PinyinHelper.toHanyuPinyinStringArray(c, PINYIN_FORMAT);
        } catch (BadHanyuPinyinOutputFormatCombination e) {
            e.printStackTrace();
        }
        return null;
    }

}

测试结果

java 复制代码

/**
 * @author TXD
 * @version 1.0   2026-04-27
 */

public class Client {
    public static void main(String[] args) {
        System.out.println(PinyinUtils.toPinyin("我爱Java"));
        System.out.println(PinyinUtils.toFirstLetter("我爱Java"));
        System.out.println(Arrays.toString(PinyinUtils.getMultiPinyin('行')));
    }
}

3. 格式化参数说明（自定义拼音格式）

参数	可选值	效果
大小写	`LOWERCASE`	zhongguo
	`UPPERCASE`	ZHONGGUO
声调	`WITHOUT_TONE`	无声调
	`WITH_TONE_NUMBER`	数字声调：zhong1 guo2
	`WITH_TONE_MARK`	符号声调：zhōng guó
ü 处理	`WITH_V`	用 v 代替：nv
	`WITH_U_UNICODE`	标准 ü：nü

3、pinyin4j踩坑

作者遇到的问题：如果未设置ü 处理，则默认针对v的处理是向后面拼接冒号

例如：我这边先注释掉对ü的处理

看结果可以发现将冒号拼接到后面了，导致后续的业务失败。。。