pinyin v2 API 完整實戰指南：漢字拼音轉換、多音字處理與拼音排序

• CLI
• NLP

本文以 pinyin（漢字拼音轉換工具）v2 API 文檔為主體，完整講解其安裝方式、核心轉換方法、五種拼音風格與兩種拼音模式，並結合本倉庫 packages/pinyin 的實際源碼（PinyinBase.ts、format.ts、constant.ts）剖析底層實現。讀完本文，你將掌握如何在 Node 與瀏覽器環境中完成漢字注音、按拼音排序、多音字處理以及姓名場景的姓氏注音。

語言版本：簡體中文 | English | 繁體中文（本文）

pinyin 是一個將中文字元轉換為拼音的 JavaScript 模組，可用於漢字注音、排序、檢索等場景。它同時支持在 Node 服務器端與 Web 瀏覽器端運行。需要說明的是，本倉庫當前源碼為 4.x 版本（見 packages/pinyin/package.json 中的"version": "4.0.0"），但 4.x 在源碼層面明確保留了對 v2 API 的兼容——在 PinyinBase.ts 中，STYLE_*與MODE_*靜態屬性均標註為「兼容 v2.x 中的屬性透出」，因此本文介紹的 v2 用法在當前倉庫代碼中依然有效。

特性一覽

• 根據詞組智能匹配最正確的拼音（依賴分詞算法解決多音字問題）。
• 支持多音字（heteronym）輸出。
• 簡單的繁體支持。
• 支持多種不同拼音風格（STYLE_NORMAL、STYLE_TONE、STYLE_TONE2、STYLE_TO3NE、STYLE_INITIALS、STYLE_FIRST_LETTER）。

安裝

通過 npm 安裝 v2 版本：

npm install pinyin@2.0 --save

安裝完成後，Node 環境中即可通過require("pinyin")引入模組。

從當前倉庫源碼看，pinyin 包同時提供main（CJS）、module（ESM）與browser（UMD）三種入口，並在bin字段註冊了pinyin命令行工具（見 packages/pinyin/package.json）。

用法

開發者用法

var pinyin = require("pinyin"); console.log(pinyin("中心")); // [ [ 'zhōng' ], [ 'xīn' ] ] 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' ] ]

從上面的例子可以看到：

• 返回值是二維數組：第一維的每一項對應輸入字符串中的一個漢字（或詞組/非中文片段），第二維是該漢字的所有讀音列表。
• 不開啟多音字模式時，「中」只返回zhōng；開啟後返回zhōng與zhòng兩個讀音。
• 開啟分詞後，「中心」被識別為一個詞組，從而正確鎖定zhōng，這正是「根據詞組智能匹配最正確的拼音」的體現。
• 開啟group: true後，「我喜歡你」被按詞組分組為wǒ、xǐhuān、nǐ三段。

命令行用法

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

pinyin命令直接將輸入的漢字轉換為帶聲調拼音；pinyin -h可查看命令行工具的完整參數說明。

API 詳解

<Array> pinyin(words[, options])

將傳入的中文字符串（words）轉換成拼音字符串數組。

options參數是可選的，可用於設定拼音風格、開啟多音字選項或啟用分詞。返回二維數組，第一維每個數組項的位置對應輸入中文字符串的每個位置，第二維是各個漢字的讀音列表——多音字會包含多個拼音項。

從源碼看，該方法對非字符串輸入做了容錯處理：當hans不是字符串時直接返回空數組（見 PinyinBase.ts）。

Number pinyin.compare(a, b)

按拼音排序的默認比較算法，可直接作為Array.prototype.sort()的回調函數使用。

其底層實現是：先將兩個漢字分別以STYLE_TONE2（數字聲調）風格轉換為拼音，再對結果進行localeCompare比較（見 PinyinBase.ts）。該行為在 test.ts 中有對應測試用例驗證：

• "我要排序".split("")排序後得到"排我序要"；
• 同音節不同聲調（馬罵媽麻）排序後得到"媽麻馬罵"，說明比較時會將聲調納入排序依據。

參數詳解

<Boolean> options.segment

是否啟用分詞模式。中文分詞有助於極大降低多音字問題的誤判率，但會導致性能明顯下降、內存佔用增加。默認不開啟。

從源碼看，開啟分詞後，轉換流程會從「逐字轉換」切換到「先分詞、再按詞組轉換」的路徑：segment_pinyin()將文本切分為詞組，長度大於 1 的詞組交給phrases_pinyin()查詢詞組拼音詞典DICT_PHRASES（數據見 packages/pinyin/src/data/phrases-dict.ts），未命中詞典時再退回逐字轉換（見 PinyinBase.ts）。

補充：當前倉庫的 4.x 源碼將segment擴展為可指定具體分詞引擎的字符串，支持"nodejieba"（默認，C++ 實現）、"Intl.Segmenter"、"segmentit"、"@node-rs/jieba"（Rust 實現），傳入true時使用Intl.Segmenter（見 segment.ts 與 util.ts）。v2 文檔中的布爾用法仍然兼容。

<Boolean> options.heteronym

是否啟用多音字模式，默認關閉。

• 關閉多音字模式時，每個漢字只返回第一個匹配的拼音（如「中心」→[['zhōng'], ['xīn']]）。
• 啟用多音字模式時，返回該漢字的所有讀音列表（如「中心」→[['zhōng', 'zhòng'], ['xīn']]）。

源碼中，單字轉換single_pinyin()會從單字詞典DICT_ZI（見 packages/pinyin/src/data/dict-zi.ts）讀取以逗號分隔的全部讀音：非多音字模式直接取第一個並按目標風格格式化；多音字模式則遍歷所有讀音，並通過緩存去重——因為不同讀音在轉換為非注音風格後可能產生重複結果（見 PinyinBase.ts）。

<Boolean> options.group

按詞組對拼音進行分組。例如：

我喜歡你 wǒ xǐhuān nǐ

開啟group: true（同時需要開啟segment: true）後，輸出的第一維不再是逐字，而是逐詞組。源碼中的groupPhrases()會將詞組內多個字的拼音通過笛卡爾積組合（combo，見 util.ts），例如詞組「朝陽」在開啟多音字時可組合出zhāoyáng與cháoyáng兩種形式——該行為同樣有測試用例覆蓋（見 test.ts）。

<Object> options.style

指定拼音風格，通過STYLE_開頭的靜態屬性進行指定，默認值為STYLE_TONE（帶聲調風格）。詳見下文「靜態屬性」一節。

options.mode

拼音模式，默認為pinyin.MODE_NORMAL普通模式。如果你明確處於姓名場景，可以使用pinyin.MODE_SURNAME，讓姓氏使用更準確的拼音。

從源碼看，MODE_SURNAME會走獨立的姓名轉換鏈路：surname_pinyin()→compound_surname()/single_surname()，依次匹配復姓詞典CompoundSurnamePinyinData（見 packages/pinyin/src/data/compound_surname.ts）與單姓詞典SurnamePinyinData（見 packages/pinyin/src/data/surname.ts），命中姓氏數據時優先採用姓氏讀音，未命中則退回普通單字轉換（見 PinyinBase.ts）。

靜態屬性：拼音風格

.STYLE_NORMAL

普通風格，不帶聲調。

如：pin yin

源碼實現：將帶聲調字符替換為對應的無聲調字母（見 format.ts）。

.STYLE_TONE

聲調風格，聲調標注在韻母第一個字母上。

注意：這是默認風格。

如：pīn yīn

源碼中該風格為toFixed()的默認分支，直接返回詞典中的原始帶聲調拼音（見 format.ts）。

.STYLE_TONE2

聲調風格 2，聲調以數字形式跟在拼音之後，用數字 [0-4] 表示。

如：pin1 yin1

源碼通過PHONETIC_SYMBOL映射表（ā→a1、á→a2、ǎ→a3、à→a4，ü→v0等，見 constant.ts）將帶聲調字符轉為「字母+數字」，再把聲調數字移動到拼音末尾（見 format.ts）。

.STYLE_TO3NE

聲調風格 3，聲調以數字形式標注在注音字符之後，用數字 [0-4] 表示。

如：pi1n yi1n

與 TONE2 的區別在於數字的位置：TONE2 是pin1（數字在整個拼音後），TO3NE 是pi1n（數字在韻母字母後）。源碼直接將帶聲調字符替換為PHONETIC_SYMBOL中的「字母+數字」形式即可得到該風格（見 format.ts）。

.STYLE_INITIALS

聲母風格，只返回各個拼音的聲母部分。對於沒有聲母的漢字，返回空字符串""。

如：「中國」的拼音為zh g。

注意：聲母風格會區分zh和z、ch和c、sh和s。源碼中的聲母表為b,p,m,f,d,t,n,l,g,k,h,j,q,x,r,zh,ch,sh,z,c,s（見 constant.ts），initials()函數按表逐一匹配拼音前綴，匹配不到則返回空字符串（見 format.ts）。

再次注意：部分漢字沒有聲母，如「啊」、「餓」等；另外y、w、yu都不是聲母，這些漢字的聲母風格輸出會是""。請仔細考慮你的需求是否應該使用首字母風格。詳情請參考下文〈為什麼沒有 y、w、yu 幾個聲母〉一節。

.STYLE_FIRST_LETTER

首字母風格，只返回拼音的首字母部分。

如：p y

源碼實現：取拼音第一個字符，若該字符是帶聲調字符（如ā），則先還原為無聲調字母再取首字母（見 format.ts）。

補充：當前倉庫源碼還提供.STYLE_PASSPORT（護照風格），輸出全大寫拼音，且ü按護照規則輸出為YU（lüe/nüe特殊處理為LUE/NUE），詳見 constant.ts 與 format.ts。此外，style參數還支持字符串形式（如"tone"、"initials"）與數字形式（如1、3）的兼容寫法，映射關係見 util.ts。

靜態屬性：拼音模式

.MODE_NORMAL

普通模式，自動識別讀音。這是默認模式，對應源碼中的ENUM_PINYIN_MODE.NORMAL（見 constant.ts）。

.MODE_SURNAME

姓名模式，對於明確的姓名場景，可以更準確地識別姓氏的讀音。例如「單」作為姓氏讀shàn，作為普通字讀dān；開啟該模式後，源碼會優先在 surname.ts 與 compound_surname.ts 兩張姓氏詞典中查詢讀音，並能識別「歐陽」「司馬」等復姓場景。

底層轉換流程

結合源碼，可以將一次完整的拼音轉換總結為以下流程（見 PinyinBase.ts 的pinyin()入口與normal_pinyin()/segment_pinyin()分支）：

1. 模式判斷：若mode為MODE_SURNAME，走姓名轉換鏈路；否則進入下一步。
2. 是否分詞：開啟segment時先調用分詞算法將文本切分為詞組，再逐詞組轉換；未開啟時逐字轉換。
3. 單字/詞組查表：單字從DICT_ZI查讀音，詞組從DICT_PHRASES查讀音，未命中的詞組退回逐字處理。
4. 風格格式化：通過toFixed()（見 format.ts）將原始帶聲調拼音轉換為目標風格。
5. 非中文片段：連續的非中文字符作為一個整體原樣輸出（不轉換為拼音），例如「我愛你 2026」中的空格與數字會被保留在輸出數組中。

另外，當前倉庫源碼還提供pinyin.compact()方法與compact選項：可將多音字的不同組合以「緊湊」形式展開為多個完整句子拼音組合（如[[nǐ],[hǎo,hào],[ma]]展開為nǐhǎoma、nǐhǎoma等組合），其笛卡爾積實現見 util.ts。

測試

v2 文檔中執行測試的方式：

npm test

從當前倉庫源碼看，pinyin 包的測試由 Jest 驅動（packages/pinyin/package.json 中"test": "jest --coverage"），測試用例覆蓋了全部風格轉換、多音字、詞組分組、姓名模式與拼音排序比較等場景（見 packages/pinyin/test/test.ts），可作為驗證本文各示例輸出的權威依據。

Q&A

關於 Web 版如何使用

首先，建議大家優先考慮在服務端一次性轉換拼音並將結果持久化，避免在客戶端每次轉換消耗性能、影響體驗。

如果你堅持在客戶端使用，可以考慮使用 Webpack + Babel 將代碼轉換為低端瀏覽器可執行的版本。從源碼看，pinyin 包的 UMD 構建（browser入口，見 packages/pinyin/package.json）即面向瀏覽器環境，Web 版入口見 packages/pinyin/src/pinyin-web.ts；倉庫還提供了經壓縮合併的dict.bin二進制字典數據（見 packages/pinyin/src/data/dict.bin），以降低網絡傳輸體積。

為什麼沒有y、w、yu幾個聲母？

聲母風格（STYLE_INITIALS）下，「雨」、「我」、「圓」等漢字返回空字符串，因為根據《漢語拼音方案》，y、w、ü (yu)都不是聲母——在某些特定韻母無聲母時，才加上y或w，而ü也有其特定規則。

這在源碼中有直接體現：聲母表INITIALS只包含b,p,m,f,d,t,n,l,g,k,h,j,q,x,r,zh,ch,sh,z,c,s，確實不含y、w（見 constant.ts），而韻母表FINALS中以v表示ü（見 constant.ts），說明ü被視為韻母而非聲母處理。

如果你覺得這帶來了麻煩，那麼也要小心一些無聲母的漢字（如「啊」、「餓」、「按」、「昂」等）。這時候你也許需要的是首字母風格（STYLE_FIRST_LETTER）。

如何實現按拼音排序？

pinyin 模組提供了默認的排序方案：

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

如果默認的比較方法不能滿足你的需求，可以自定義pinyinCompare方法：

const pinyin = require('pinyin'); const data = '我要排序'.split(''); // 建議將漢字的拼音持久化存儲起來。 const pinyinData = data.map(han => ({ han: han, pinyin: pinyin(han)[0][0], // 可以自行選擇不同的生成拼音方案和風格。 })); const sortedData = pinyinData.sort((a, b) => { return a.pinyin.localeCompare(b.pinyin); }).map(d => d.han);

自定義方案的核心思路是：先將每個漢字轉為拼音並與原字捆綁，再對拼音做localeCompare比較。這樣可以自由選擇拼音風格（如不帶聲調的STYLE_NORMAL），實現不同粒度的排序需求。

Node 版和 Web 版有什麼異同？

pinyin目前可以同時運行在 Node 服務器端和 Web 瀏覽器端，API 和使用方式完全一致。

但 Web 版較 Node 版稍簡單：拼音庫只有常用字部分，沒有使用分詞算法，並考慮網絡傳輸對詞庫進行了壓縮處理。由於分詞和繁體中文的特性，部分情況下的結果也不盡相同。

由於這些區別，測試不同運行環境的用例也不盡相同。從源碼結構看，Node 版入口 pinyin.ts 額外提供了segment()分詞能力，而 Web 版入口 pinyin-web.ts 不帶分詞，兩者共享同一套PinyinBase核心邏輯。

許可證

本項目以 MIT 許可證發佈（見倉庫根目錄 LICENSE 與 packages/pinyin/package.json 中的"license": "MIT"）。

• CLI
• NLP