2025最强拼音库pinyin.js使用攻略：多音字与分词一站式搞定

简介

pīnyīn 中文汉字拼音转换工具, 支持多音字, 支持姓氏模式, 支持排序, 支持 CLI 命令行使用。

安装

pnpm add pinyin

快速上手

import { pinyin } from "pinyin";

pinyin("你好");
// [["nǐ"], ["hǎo"]];

import { pinyin } from "pinyin";

pinyin("前端开发技术前沿", {
  segment: true, // 启用中文分词
  group: true, // 按词组分组
});
// [["qiánduān"], ["kāifā"], ["jìshù"], ["qiányán"]];

API

• string[][] pinyin(words, options?)
• 将中文字符串转换为二维数组形式的拼音结果
• 外层数组按输入文本逐字或逐词(当启用分词/分组)排列
• 内层数组为该字或词的可能读音列表(多音字返回多个)
• number pinyin.compare(a, b)
• 基于拼音的默认排序比较函数
• string[][] pinyin.compact(result)
• 将多音字的组合进行压缩为紧凑形式，配合 options.compact

选项 IPinyinOptions

• style?: IPinyinStyle
• 拼音输出风格，默认 tone
• 取值(推荐使用小写字符串)：
  • normal 普通风格，不带声调
  • tone 声调风格，带音标
  • tone2 声调以数字后缀标注，如 pin1
  • to3ne 声调以数字插入注音字符后，如 pi1n
  • initials 仅声母，如 zh
  • first_letter 首字母，如 p
  • passport 护照标准风格(特殊场景)
• 兼容值：NORMAL|TONE|TONE2|TO3NE|INITIALS|FIRST_LETTER|PASSPORT 或数字 0|1|2|5|3|4
• mode?: IPinyinMode
• 拼音模式，默认 normal
• 取值：normal | surname
  • surname 姓氏模式，优先返回姓氏惯用读音
• segment?: IPinyinSegment | boolean
• 是否启用中文分词，或指定分词库
• 可选值：true|false 或 "Intl.Segmenter" | "nodejieba" | "segmentit" | "@node-rs/jieba"
• heteronym?: boolean
• 是否返回多音字的所有读音，默认 false
• group?: boolean
• 是否按词组分组返回拼音，常与 segment: true 一起使用
• compact?: boolean
• 是否将多音组合压缩为紧凑结果，配合 pinyin.compact

风格示例

import { pinyin } from "pinyin";

pinyin("拼音", { style: "normal" }); // 普通风格
pinyin("拼音", { style: "tone" }); // 声调风格
pinyin("拼音", { style: "tone2" }); // 声调以数字后缀标注
pinyin("拼音", { style: "to3ne" }); // 声调以数字插入注音字符后
pinyin("中国", { style: "initials" }); // 仅声母
pinyin("拼音", { style: "first_letter" }); // 首字母

多音字与分词

import { pinyin } from "pinyin";

pinyin("中心", { heteronym: true, segment: true });
// [["zhōng"], ["xīn"]];

指定分词实现

import { pinyin } from "pinyin";

pinyin("前端开发", { segment: true });
// [["qián"], ["duān"], ["kāi"], ["fā"]];

分词库	描述
Intl.Segmenter	浏览器原生分词器，支持中文、英文等多语言
nodejieba	Node.js 分词库，基于 C++ 实现，性能高
segmentit	Node.js 分词库，基于 Rust 实现，性能高
@node-rs/jieba	Node.js 分词库，基于 Rust 实现，性能高

segment: true 默认分词库，Intl.Segmenter 。

姓氏模式示例

import { pinyin } from "pinyin";

pinyin("华夫人", { mode: "surname" });
// [["huà"], ["fū"], ["rén"]];

排序示例

import { pinyin } from "pinyin";

const data = "我要排序".split("");
const sorted = data.sort(pinyin.compare);
// ["要", "我", "序", "排"]

CLI

• 安装后可直接在命令行使用：
• pinyin 前端开发技术前沿
• 查看帮助：pinyin -h

-h, --help                   输出帮助信息
-V, --version                输出 pinyin 命令行工具的版本号
-v, --version                输出 pinyin 命令行工具的版本号
-s, --style <style>          pinyin 风格: [NORMAL,TONE,TONE2,INITIALS,FIRST_LETTER]
-m, --mode <mode>            pinyin 模式: [NORMAL,SURNAME]
-S, --segment [segment]      词组分词， 支持 "Intl.Segmenter", "nodejieba", "@node-rs/jieba", "segmentit"
-h, --heteronym              多音字输出多个拼音
-g, --group                  词组以分组格式输出
-c, --compact                输出紧凑模式
-p, --separator <separator>  指定分隔符

注意事项

• 分词与准确率
• 分词可显著降低多音字误判并提升短语读音准确率
• 在部分版本中默认开启分词以提高准确率，可通过 segment 显式关闭或切换实现
• 浏览器与 Node 差异
• 浏览器通常支持 Intl.Segmenter 与 segmentit
• Node 环境可选择更多分词库，例如 nodejieba、@node-rs/jieba
• 风格选择建议
• 列表检索与排序常用 normal 或 passport
• 注音展示常用 tone
• 缩写场景可用 first_letter 或 initials

参考

• GitHub：https://github.com/hotoo/pinyin
• 文档：https://pinyin.js.org/index.html