pinyin v4 完整 API 指南：汉字拼音转换、多音字处理与分词实战

• CLI
• NLP

导读

pinyin是 pinyin 项目中负责「汉字 ➜ 拼音」转换的核心 npm 包（v4 版本），面向拼音标注、按拼音排序、中文搜索等场景设计。本文以仓库内 v4 API 文档 为骨架，结合 核心实现 与 类型声明，完整讲解pinyin()函数、全部选项（style/mode/segment/heteronym/group/compact）、静态属性、CLI 用法以及按拼音排序的实战方案。读完本文，你将掌握 v4 版本的完整 API 面，并能根据多音字、姓名、分词等场景正确选配参数。

一、模块定位与适用环境

文档开篇即明确了模块定位：Convert Han to pinyin, useful for phonetic notation, sorting, and searching（汉字转拼音，用于注音、排序和检索）。核心特性有三点：

• 面向多音字词组的分词支持（Segmentation for heteronym words）；
• 同时支持简体与繁体中文（Support Traditional and Simplified Chinese）；
• 支持多种拼音输出风格（Support multiple pinyin style）。

该模块同时支持Node.js 与 Web 浏览器两种运行环境，这一点也体现在打包产物上：packages/pinyin/package.json中同时声明了main（CJS）、module（ESM）与browser（UMD）三个入口，且engines.install-node要求 Node 版本不低于 18。

二、安装

通过 npm 安装（文档给出的标准方式）：

npm install pinyin --save

包本身只有commander（供 CLI 使用）一个运行时依赖；分词器@node-rs/jieba与segmentit均声明为可选的 peerDependencies（见 package.json），只有当你需要segment选项使用这两个分词器时才需要额外安装。仓库根目录使用 pnpm workspace 管理，在 monorepo 环境中也可以直接以 workspace 方式引用该包。

三、快速上手

3.1 开发环境（TypeScript / ESM）

文档给出的最基础用法：

import { pinyin } from "pinyin"; console.log(pinyin("中心")); // [ [ 'zhōng' ], [ 'xīn' ] ]

注意返回结构是二维数组Array<Array<string>>：外层数组的每个元素对应输入中的一个汉字（或一个分词后的词），内层数组是该字（词）的拼音候选列表——默认只取第一个读音，因此内层只有一个元素。

逐步叠加选项：

// 开启多音字模式：返回一个汉字的全部读音 console.log(pinyin("中心", { heteronym: true })); // [ [ 'zhōng', 'zhòng' ], [ 'xīn' ] ] // 开启分词：修复绝大多数多音字误读问题 console.log(pinyin("中心", { heteronym: true, segment: true })); // [ [ 'zhōng' ], [ 'xīn' ] ] // 分词 + 分组：按词组输出 console.log(pinyin("我喜欢你", { segment: true, group: true })); // [ [ 'wǒ' ], [ 'xǐhuān' ], [ 'nǐ' ] ] // 指定拼音风格 + 多音字 console.log(pinyin("中心", { style: pinyin.STYLE_INITIALS, heteronym: true })); // [ [ 'zh' ], [ 'x' ] ] // 姓名模式：优先取姓氏读音 console.log(pinyin("华夫人", { mode: "surname" })); // [ ['huà'], ['fū'], ['rén'] ]

3.2 命令行环境（CLI）

包通过bin字段暴露了pinyin可执行文件：

$ pinyin 中心 zhōng xīn $ pinyin -h

默认情况下 CLI 会把二维结果摊平为空格分隔的一维拼音串输出。

四、类型系统详解

v4 是 TypeScript 编写的强类型版本，所有选项都有明确的类型定义，定义见 declare.ts 并通过 包入口 对外导出IPinyinOptions、IPinyinStyle、IPinyinSegment等类型。

4.1 IPinyinOptions

pinyin()方法的第二个参数类型：

export interface IPinyinOptions { style?: IPinyinStyle; // output style of pinyin. mode?: IPinyinMode, // mode of pinyin. segment?: IPinyinSegment | boolean; heteronym?: boolean; group?: boolean; compact?: boolean; }

内部强类型IPinyinAllOptions（见 declare.ts）则把每个字段收敛为唯一合法值，其中compact的语义注释给出了直观示例：

• compact=false（默认）：[[nǐ], [hǎo,hào], [ma,má,mǎ]]——每个字各自携带多音候选；
• compact=true：输出所有读音的笛卡尔积组合，如[nǐ,hǎo,ma]、[nǐ,hǎo,má]、[nǐ,hào,mǎ]等完整序列。

4.2 IPinyinStyle

拼音输出风格，支持字符串（小写/大写）与数字两种写法，数字为兼容旧版本：

export type IPinyinStyle = "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | // 推荐 "NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" | 0 | 1 | 2 | 5 | 3 | 4; // 兼容

在 util.ts 中，字符串与数字写法通过pinyinStyleMap统一映射为内部枚举：normal/0、tone/1、tone2/2、initials/3、first_letter/4、to3ne/5，另有 v4 新增的passport/6（护照风格，见下文静态属性）。非法值会回退到默认的TONE。

4.3 IPinyinMode

转换模式，目前支持普通与姓名两种：

// - NORMAL: Default mode is normal mode. // - SURNAME: surname mode, for chinese surname. export type IPinyinMode = "normal" | "surname" | "NORMAL" | "SURNAME";

4.4 IPinyinSegment

分词器指定，默认不开启分词（false）：

• 设true：Web 与 Node 环境统一使用内置的Intl.Segmenter（zh-Hans-CN、word 粒度）；
• 也可显式指定字符串（注意文档说明："segmentit"在 Web 端可用，"nodejieba"与"@node-rs/jieba"为 Node 端实现）：

export type IPinyinSegment = "Intl.Segmenter" | "nodejieba" | "segmentit" | "@node-rs/jieba";

五、核心 API

5.1<Array> pinyin(words[, options])

将汉字（Han）转换为拼音，options可省略。返回值类型为Array<Array<String>>，当某个汉字是多音字时，其内层数组会包含多个拼音。入口实现在 pinyin.ts 与 PinyinBase.ts：

• 内部先调用convertUserOptions合并默认值（见 constant.ts 的DEFAULT_OPTIONS：style=TONE、mode=NORMAL、heteronym=false、group=false、compact=false）；
• 若mode === SURNAME走姓名专用流程；否则按是否开启segment分流到分词转换（segment_pinyin）或单字转换（normal_pinyin）；
• 非中文字符（数字、字母、标点）会原样保留，连续的非中文片段作为一个整体输出，不参与拼音转换（见normal_pinyin的nohans缓存逻辑）。

5.2Number pinyin.compare(a, b)

默认的拼音比较实现，可直接传给Array.prototype.sort做拼音排序。底层实现（PinyinBase.ts）是：把两个入参分别用STYLE_TONE2风格转成拼音后，对字符串结果做localeCompare。

5.3pinyin.compact(arr)

将二维数组按多音字候选做笛卡尔积组合（见 util.ts），是options.compact的底层实现，也可作为独立工具函数使用。

六、选项逐项解析

6.1options.segment（分词开关）

默认false。开启后会对输入文本先行分词，再按词注音。文档明确提示：分词有助于修复多音字误读，但性能更慢，需要更多 CPU 与内存。从实现看，分词路径调用this.segment(hans, options.segment)（segment.ts），四种分词器按优先级依次尝试：

• "@node-rs/jieba"：Rust 实现的 jieba，首次调用时执行load()加载词典，之后用cut(hans, false)切词；
• "segmentit"：Node 端纯 JS 分词，使用useDefault(new Segment())默认词典，simple: true输出纯词串；
• "Intl.Segmenter"：基于Intl.Segmenter("zh-Hans-CN", { granularity: "word" })，无第三方依赖，Web/Node 通用；
• "nodejieba"（兜底默认）：C++ 实现的 jieba，调用cutSmall(hans, 4)。

若指定分词器未安装（peerDependencies 缺失），会打印提示并退化为整串原样返回；异常时也会catch后原样返回。

6.2options.heteronym（多音字开关）

默认false。开启后返回该字的全部读音。底层实现在single_pinyin（PinyinBase.ts）：从字表DICT_ZI中取出以逗号分隔的读音数组，逐一按目标风格转换；若转换为非注音风格（如 initials）后出现重复，会通过缓存去重。测试用例（test/test.ts）验证了「中」在heteronym下输出['zhōng', 'zhòng']。

6.3options.group（词组分组）

与segment配合使用，按分词结果把拼音合并到词组级。例如「我喜欢你」分到词后输出[ ['wǒ'], ['xǐhuān'], ['nǐ'] ]——xǐhuān成为整体。实现上调用groupPhrases（PinyinBase.ts），底层由combo（util.ts）对多音字候选做组合拼接。该选项单独使用没有意义，文档示例中均与segment: true搭配。

6.4options.style（拼音风格）

指定输出风格，文档建议使用STYLE_*静态属性，默认.STYLE_TONE。实际转换逻辑集中在 format.ts 的toFixed()函数：

• 声调符号与数字的映射表PHONETIC_SYMBOL（见 constant.ts）把ā→a1、á→a2等一一对应；
• NORMAL通过正则去掉声调符号只留字母；
• TONE2把声调转为拼音末尾的数字；
• TO3NE把声调数字放在韵母首字母后（如li2ng）；
• INITIALS从声母表INITIALS（见 constant.ts）中匹配开头声母，无声母的汉字（如「爱」「我」）返回空字符串，这一点文档已特别提示；
• FIRST_LETTER只取首字母，若首字母是带调字符则先映射回字母；
• PASSPORT先归一为无调字母，再处理ü：lü/nü → LYU/NYU，lüe/nüe → LUE/NUE，最后整体大写（测试用例见 test/test.ts 中「吕→LYU」「略→LUE」）。

6.5options.mode（转换模式）

默认pinyin.MODE_NORMAL。姓名场景建议使用pinyin.MODE_SURNAME。源码中SURNAME模式走独立的surname_pinyin流程（PinyinBase.ts）：

• 先检测复姓（如「欧阳」），查compound_surname数据表，命中则整体注音并跳过这两个字符；
• 剩余部分按单姓逐个处理，查SurnamePinyinData优先取姓氏读音，未收录的字回落到single_pinyin；
• 例如「华夫人」：姓氏「华」取huà（而非通用的huá），输出[ ['huà'], ['fū'], ['rén'] ]。

七、静态属性速查

7.1 风格属性（pinyin.STYLE_*）

这些静态属性同时以实例属性形式挂在类上（PinyinBase.ts）与函数属性形式挂在导出的pinyin函数上（PinyinBase.ts），兼容 v2.x 的访问习惯。

7.2 模式属性（pinyin.MODE_*）

八、实战：按拼音排序

文档 Q&A 给出了两种方案。

方案一：直接使用内置compare

const pinyin = require('pinyin'); const data = '我要排序'.split(''); const sortedData = data.sort(pinyin.compare);

方案二：自定义排序（先持久化拼音结果）

const pinyin = require('pinyin'); const data = '我要排序'.split(''); // 建议将拼音结果持久化，避免重复计算。 const pinyinData = data.map(han => ({ han: han, pinyin: pinyin(han)[0][0], // 按需选择 options 与 style。 })); const sortedData = pinyinData.sort((a, b) => { return a.pinyin.localeCompare(b.pinyin); }).map(d => d.han);

compare底层已内置STYLE_TONE2+localeCompare（PinyinBase.ts），因此方案一可直接排序；方案二适合需要自定义风格（如按无调拼音排序）或需要缓存结果的场景。

九、测试与验证

仓库在 test/test.ts 中覆盖了各风格的完整用例矩阵：单音字（如「我」）、多音字（如「中」「啊」）、元音字（如「爱」）、ü系汉字（「吕」「略」「虐」）等，均逐一断言STYLE_NORMAL / PASSPORT / TONE / TONE2 / TO3NE / INITIALS / FIRST_LETTER七种输出。运行测试：

npm test

（对应jest --coverage，见 package.json。）另外 segment 测试 与 format 测试 可分别验证分词与风格转换边界。

十、Q&A 补充

Q1：多音字模式返回的读音顺序是什么？顺序即字表DICT_ZI（data/dict-zi.ts）中的记录顺序；开启分词后，命中的词组会优先查 词组拼音数据 的固定注音，从而把多音字"固化"为语境下的正确读音。

Q2：非中文内容如何处理？非中文字符不会被转拼音，而是原样输出；连续的非中文片段会合并为单个数组元素（见normal_pinyin的nohans逻辑）。

Q3：模块同时支持 Node 与浏览器吗？是。文档明确说明 "This module both support Node and Web browser"；Web 端入口为 pinyin-web.ts（浏览器版分词默认走Intl.Segmenter），Node 端入口为 pinyin.ts。

• CLI
• NLP