jieba-php 中文分词快速使用手册

适用版本：PHP7.1+ / PHP8.4
核心定位：轻量无扩展、开箱即用的PHP中文分词组件，支持简繁/多语言、关键词提取、自定义词典
项目地址：https://github.com/fukuball/jieba-php

1. 快速安装

仅保留Composer自动安装（推荐，自动管理依赖，无需手动引入文件），执行终端命令：

composer require fukuball/jieba-php

2. 组件初始化

所有功能执行前必须先初始化，提供2种初始化模式，按需选择，代码可直接复制到PHP脚本中。

基础初始化（默认大字典，支持简繁/全功能）

<?php
// 引入自动加载（Composer安装后必加）
require_once __DIR__ . '/vendor/autoload.php';
// 引入核心类
use Fukuball\Jieba\Jieba;
use Fukuball\Jieba\Finalseg;

// 初始化（处理大文本可调整内存限制，非必需）
ini_set('memory_limit', '512M');
Jieba::init();
Finalseg::init();

轻量初始化（小字典，加载更快，适配轻量场景）

// 替换基础初始化的Jieba::init()即可
Jieba::init(['mode'=>'test', 'dict'=>'small']);
Finalseg::init();

3. 核心功能快速示例

所有示例均基于已完成初始化，代码极简可直接运行，附带核心输出结果。

3.1 基础分词（三种核心模式）

jieba-php的核心能力，覆盖90%基础分词场景

// 1. 精确模式（默认，无歧义切分，适合文本分析）★★★最常用
$res1 = Jieba::cut("我来到北京清华大学");
var_dump($res1); // 输出：["我","来到","北京","清华大学"]

// 2. 全模式（扫描所有可成词，存在冗余，适合全词汇提取）
$res2 = Jieba::cut("我来到北京清华大学", true);
var_dump($res2); // 输出：["我","来","来到","北京","清华","清华大学","华大","大学"]

// 3. 搜索引擎模式（长词二次切分，提升召回率，适合搜索场景）
$res3 = Jieba::cutForSearch("小明硕士毕业于中国科学院计算所");
var_dump($res3); // 输出：["小明","硕士","毕业","中国","科学","学院","科学院","中国科学院","计算","计算所"]

3.2 加载自定义词典（补充专业术语/新词）

解决专业词汇、专属名词被错误切分的问题，词典格式必须严格遵循。

步骤1：创建自定义词典文件（如user_dict.txt）

格式：词语词频词性（空格分隔，词频/词性可选，建议填写）

创新办 5 n
云计算 10 n
李小福 3 nr

步骤2：代码加载并使用

// 加载自定义词典（初始化后执行）
Jieba::loadUserDict(__DIR__ . '/user_dict.txt');
// 分词验证
$res = Jieba::cut("李小福是创新办主任，也是云计算专家");
var_dump($res); // 输出：["李小福","是","创新办","主任","也","是","云计算","专家"]

3.3 TF-IDF关键词提取（文本核心词提取）

适用于文章摘要、热词分析，需额外引入分析类，支持指定提取数量。

// 引入关键词提取类
use Fukuball\Jieba\JiebaAnalyse;
// 初始化分析组件（初始化核心类后执行）
JiebaAnalyse::init();

// 提取前5个核心关键词（第二个参数为提取数量）
$content = "自然语言处理是人工智能的重要分支，中文分词是自然语言处理的基础步骤，jieba-php是优秀的PHP分词工具";
$tags = JiebaAnalyse::extractTags($content, 5);
var_dump($tags); // 输出：["自然语言处理","中文分词","人工智能","jieba","php"]

3.4 繁体中文分词

无需额外配置，仅需基础初始化（默认大字典），直接对繁体文本分词，兼容简繁混合场景。

// 繁体分词
$res1 = Jieba::cut("憐香惜玉也得要看對象啊！");
var_dump($res1); // 输出：["憐香惜玉","也","得","要","看","對象","啊"]
// 简繁混合
$res2 = Jieba::cut("我喜歡吃芒果，憐香惜玉是美德");
var_dump($res2); // 输出：["我","喜歡","吃","芒果","，","憐香惜玉","是","美德"]

4. 高频实用技巧

4.1 清除缓存释放内存（处理大量文本/多文件必用）

避免多次分词后内存溢出，在文本处理间隙执行：

Jieba::clearCache(); // 清除核心缓存
// 或彻底清除所有缓存
// Fukuball\Jieba\JiebaMemory::clearAllCaches();

4.2 关键词提取过滤停用词（提升准确性）

创建停用词文件（如stop_words.txt，每行一个停用词：的、是、也、啊），加载后过滤无意义词汇：

// 加载停用词（提取关键词前执行）
JiebaAnalyse::setStopWords(__DIR__ . '/stop_words.txt');
// 再执行关键词提取，会自动过滤停用词
$tags = JiebaAnalyse::extractTags($content, 5);

4.3 获取词汇在原文的位置（文本定位分析）

返回词汇+起止下标，适用于文本高亮、定位场景：

$res = Jieba::tokenize("永和服装饰品有限公司");
var_dump($res);
// 输出示例：[["word"=>"永和","start"=>0,"end"=>2],["word"=>"服装","start"=>2,"end"=>4],...]

5. 开发注意事项（避坑重点）

内存配置：处理超大文本（如万字以上），需在初始化前添加ini_set('memory_limit', '1024M')，避免内存溢出；
字典选择：轻量场景（如小程序/简单分词）用small字典，繁体/专业场景用默认大字典，不建议混用；
Web环境优化：PHP-FPM/Web项目中，建议将初始化放在全局入口（如index.php），避免每次请求重复初始化，提升性能；
无扩展依赖：纯PHP实现，无需安装任何PHP扩展（如mbstring需开启，PHP默认已开启），直接运行。

【PHP】 jieba-php 中文分词快速使用手册