Windows+VS2008下编译PostgreSQL中文分词扩展zhparser全指南

简介：在 Windows 平台上为 PostgreSQL 数据库部署中文分词扩展 zhparser 往往缺少现成参考，这份资源正是针对 VS2008 编译环境打包好的可直接使用的安装程序与完整源码工程。压缩包内共包含 138 个文件，整体约 11.19MB，c/h 源码、vcproj/sln 等 VS 工程文件、生成的 dll/lib、control 控制文件、ini 与词典配置、sql 脚本一应俱全，基本覆盖从源码编译到注册启用的完整链条。作者记录了 Windows 下编译 scws 时头文件编码导致引入失败、改用 VS 重新建立工程并配置 PostgreSQL 头文件与库文件、修正 DLL 导出函数声明、定位词典与 ini 文件至 tsearch_data 目录等关键排错过程。这些操作细节在现有 Linux 教程中极少涉及，能帮助读者绕过环境差异带来的暗坑，快速在 Windows 平台获得可用中文分词能力。资源已有 1603 人学习，适合在 Windows 上搭建 PostgreSQL 全文检索或中文分词功能的开发与运维人员参考。

1. 为什么要折腾 Windows + VS2008 下的 zhparser

zhparser 是 PostgreSQL 上最常用的中文全文检索扩展，核心作用是把中文长文本切成有语义的词，而不是让数据库按一个个单字去匹配。官方文档和网上教程几乎清一色是 Linux 环境下的编译安装，一条make && make install就完事。但在 Windows + VS2008 环境里，事情完全变了一个样：没有 PGXS 构建框架、没有 make、SCWS 源码本身带着一堆 POSIX 气息，VS2008 的 C 编译器又是严格 C89 的老古董，连stdint.h都没有。我在第一次尝试时顺手把源码拖进 VS2008 直接编译，结果报错铺满整个输出窗口，边翻工程配置边查源代码，前后折腾了一整天才真正跑通。这篇笔记把整套流程拆开讲清楚，给那些必须在老 Windows 环境、老编译器版本上落地的同学一条可以照抄的路。本文适合有 PG 基础、但第一次在 Windows 上编译扩展的开发者，以及被国产化或内网环境锁定了旧工具链的数据库维护者。

2. 动手前先摸清底牌：版本矩阵、源码包与目录规划

2.1 先看版本兼容：VS2008 能配的 PG 大版本其实很有限

zhparser 最终是一个 DLL，加载进 PostgreSQL 的进程里运行。Windows 下 PostgreSQL 本身是用 MSVC 编译的，所以插件 DLL 和数据库主程序必须共用同一套 C 运行库，否则轻则告警，重则直接加载失败。VS2008 对应的是 VC9 编译器，C 运行库是 msvcr90，这个组合在 PostgreSQL 9.x 时代是主流的 Windows 构建工具链。而到 PostgreSQL 10 之后，官方 Windows 二进制包基本换成了更新的 VS 版本，这时候拿 VS2008 编译出来的 zhparser.dll 塞进去，很可能触发 "loaded library is not a valid PostgreSQL library" 之类的问题。

我在实际项目里用的组合是 VS2008 + PostgreSQL 9.6，这个搭配下编译、加载、查询全流程都比较顺畅，也是当时 Windows 平台上遇到最多的组合。如果你的环境是 PostgreSQL 10 以上，建议先确认数据库安装包的编译工具链版本，再决定是不是要往 VS2008 方向走。这里有一个基本判断原则：插件和主程序编译器版本越接近，踩到 CRT 冲突的几率越低。

下表是我自己总结的版本搭配经验，按省事程度排序：

PostgreSQL 版本	推荐编译器	说明
9.0 - 9.2	VS2008 / VS2010	老环境最稳，CRT 冲突风险小
9.3 - 9.6	VS2008 / VS2010 / VS2013	覆盖大量存量系统
10 及以上	VS2015 及以上	VS2008 虽可尝试，但风险明显上升

判断 PostgreSQL 主程序用什么编译器编译，一个简单办法是打开 PG 安装目录下的 bin 文件夹，看依赖的运行时 DLL。如果看到 msvcr90.dll，就是 VC9；看到 msvcr100.dll 就是 VC10，以此类推。这个细节可以作为选型时的直接依据。

2.2 四个必需的材料包，少一个都白搭

编译 zhparser 之前需要先搞清楚它依赖什么。zhparser 本身是 PostgreSQL 扩展，它调用了 SCWS 分词库完成中文分词；而 SCWS 又依赖一个词典文件（xdb 格式）才能工作。所以整个链条是：zhparser → SCWS 静态库 → xdb 词典文件 → PostgreSQL 主程序。任何一个环节缺失或版本不匹配，前面工作全白做。

需要准备的材料如下：

• PostgreSQL Windows 安装包：必须选带开发组件的版本，确保 include 目录里有 postgres.h，lib 目录里有 postgres.lib
• zhparser 源码：拿到 C 源码即可，重点是 zhparser.c 和 zhparser.h 两个文件
• SCWS 源码：注意拿的是 SCWS 项目源码，不是 PHP 扩展封装部分，编译目标是一个静态库
• 词典文件：SCWS 自带的 dict.utf8.xdb 等词库文件，后续要拷贝到 PostgreSQL 能找到的路径

这里最容易踩的坑是只装了数据库主程序没装开发组件。PostgreSQL 的 Windows 安装器默认不勾选开发头文件，装完只有 bin、lib、share 目录，include 目录根本不存在。我刚开始折腾时就是在这样的环境里找了半天 postgres.h，最后只能重新运行安装器补上组件。

2.3 目录规划：把三类源码分开，别混在一个文件夹里

Windows 下编译 C 项目最怕的就是路径混乱。我习惯按下面的结构组织整个工作目录：

D:\zhparser_build\ ├── scws\ # SCWS 源码 ├── zhparser\ # zhparser 源码 ├── win_include\ # 补丁用头文件，如 unistd.h └── output\ # 编译输出和最终安装文件

这样做的目的一方面是让各个工程之间 include 路径的引用关系简单清晰，另一方面是将来排查问题时能快速定位到具体文件。VS2008 工程文件放在各自源码目录下，输出的 DLL 和中间文件统一指到 output 文件夹。

打开 VS2008 命令行工具后，建议先把环境变量设好，然后用下面的批处理把编译环境固定下来：

set PGHOME=C:\Program Files\PostgreSQL\9.6 set PG_INCLUDE=%PGHOME%\include set PG_LIB=%PGHOME%\lib set SCWS_SRC=D:\zhparser_build\scws set ZHPARSER_SRC=D:\zhparser_build\zhparser call "C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat" x86

这里vcvarsall.bat是 VS2008 提供的环境初始化脚本，参数 x86 指定生成 32 位代码。PostgreSQL 9.x 的官方 Windows 包基本都是 32 位，所以这里目标平台选 x86，不要选 x64，否则后面链接 stage 会遇到平台不匹配的错误。如果你的 PG 本身是 64 位安装包，这里的参数则相应改成 x64，且整个链路都要统一成 64 位。

3. 先拿下 SCWS：把中文分词核心库编成 VS2008 静态库

3.1 SCWS 是什么，zhparser 为什么离不开它

SCWS 是一个开源的中文分词系统，支持 UTF-8 编码，内部使用 xdb 格式的词典做词条匹配。zhparser 并不自己实现分词算法，而是把 SCWS 当作底层引擎：收到待分词的文本后，调用 SCWS 的接口切出词序列，再把切词结果映射成 PostgreSQL 全文检索的 token 类型。所以编译 zhparser 之前必须先得到一份能链接的 SCWS 库文件。

SCWS 源码是纯 C 写的，但它的目标平台偏向 Linux，代码里夹杂着 unistd.h、gettimeofday、strcasecmp 这些 POSIX 接口。在 VS2008 下编译，这些 API 恰恰是雷区。VS2008 的 C 编译器只支持相对完整的 C89，距离 SCWS 源码里实际使用的 C99 写法还有一段距离。因此编译 SCWS 的核心工作并不是直接点"编译"按钮，而是先做平台兼容性适配，再建立工程编译。

3.2 用 VS2008 建 SCWS 静态库工程的正确姿势

打开 VS2008，新建一个 Win32 项目，在向导里选择"静态库"并取消"预编译头"选项。SCWS 的项目文件不建议用现有的 Makefile 转换，而是手动把源码目录下需要用到的.c文件添加进来。要注意只加入核心库的实现文件，SCWS 自带的命令行工具、测试程序统统不要加入工程，这些代码往往带 main 函数或者在编译时有较多的平台依赖，加进来只会拖慢进度。

添加文件时，可以参考以下核心模块清单，不同版本 SCWS 文件名略有差异，以工程能通过编译为准：

scws_analysis.c # 文本切分主逻辑 scws_rule.c # 规则选项处理 scws_dict.c # 词典加载与匹配 scws_mmap.c # mmap 文件读取封装 xdb.c # xdb 词典格式解析

建立工程后，需要立刻修改两个地方。第一是"配置属性 → C/C++ → 高级 → 编译为"，把选项改成"编译为 C 代码 (/TC)"，因为 SCWS 的源码是 C 不是 C++，如果让 VS2008 按 C++ 编译，很多类型转换的报错会让你怀疑人生。第二是"配置属性 → C/C++ → 预处理器 → 预处理器定义"里加入：

_CRT_SECURE_NO_WARNINGS _CRT_NONSTDC_NO_DEPRECATE WIN32

第一个宏的含义是屏蔽掉 VS2008 对strcpy、sprintf这类函数的安全性检查告警，这些函数在 SCWS 源码里大量出现，不关掉警告会导致输出窗口被刷屏且影响对真正错误的判断。第二个宏是禁止对 POSIX 风格函数名的废弃告警，第三个宏告诉代码当前是 Windows 平台。

3.3 三个必须提前堵死的编译错误

第一号坑是unistd.h找不到。VS2008 根本没有这个头文件，而 SCWS 源码里至少有一处会#include <unistd.h>。解决方式是自己在 win_include 目录下补一个极简的 unistd.h 文件：

#ifndef _MSC_VER_UNISTD_H_ #define _MSC_VER_UNISTD_H_ #include <io.h> #include <process.h> #endif

然后在工程的"附加包含目录"里把D:\zhparser_build\win_include加到最前面。这个文件只做一件事：把 unistd.h 暴露的常用函数映射到 Windows 的_read、_write、_getpid等版本上，让源码能通过编译即可。

第二号坑是stdint.h缺失。VS2008 的这个头文件从 VS2010 才开始提供。SCWS 和后续 zhparser 的源码里可能直接包含<stdint.h>。最简单可靠的做法是从安装了 VS2010 或更高版本 VS 的机器上拷贝一份stdint.h头文件放入 win_include 目录，然后同样通过附加包含目录让它生效。这个文件是微软官方出的标准头文件，拷贝使用不会产生授权或兼容问题。

第三号坑是 C99 语法在 C89 模式下编译失败。SCWS 源码里如果出现变量声明在语句之后、指定初始化器、inline关键字等情况，VS2008 会报 C2059 语法错误或 C2055 之类的错误。处理方法不复杂，按错误提示定位到具体行，把变量声明统一挪到代码块开头，inline改成__inline即可。这类修改不影响运行时行为，只是迎合编译器。

完成以上适配后，编译 SCWS 静态库一般就能通过。生成的文件是scws.lib，记下输出路径，下一步编译 zhparser 时要用。如果还遇到其他零零散散的编译错误，优先检查是不是又引入了不属于核心库的源码文件，这一条能过滤掉大半问题。

4. 编译 zhparser 本体：从 C 源码到 zhparser.dll 的完整过程

4.1 新建 DLL 工程，先把 include 路径配对

zhparser 的编译目标是生成一个 PostgreSQL 扩展 DLL。在 VS2008 里新建一个 Win32 项目，类型选"动态链接库"，空项目即可。然后把 zhparser.c 加入工程，如果源码包里还有 zhparser.h 头文件，也一并放进工程目录。zhparser.c 顶部有#include "postgres.h"这一行，它决定了后续 include 路径必须指向 PostgreSQL 安装包里的 include 目录。这一步很容易出问题：很多人配路径时只指向了 include 的上级目录，结果编译时找不到 postgres.h。

正确的附加包含目录配置应该是：

D:\zhparser_build\win_include C:\Program Files\PostgreSQL\9.6\include C:\Program Files\PostgreSQL\9.6\include\server C:\Program Files\PostgreSQL\9.6\include\server\port\win32

强调一下include\server这个子目录，postgres.h 实际就在这个目录下，少配这一层必然报"无法打开包含文件 postgres.h"。最后那一层是 Windows 平台相关的移植头文件目录，zhparser.c 里有一些平台判断逻辑会引用它。win_include 放在最前面，是为了让前面补丁过的 unistd.h、stdint.h 优先被找到，避免误用其他目录里的同名文件。

同时，在预处理器定义里加上：

_CRT_SECURE_NO_WARNINGS _CRT_NONSTDC_NO_DEPRECATE WIN32 PG_MODULE_MAGIC_USE

补充说明一下PG_MODULE_MAGIC_USE：zhparser.c 里虽然已经写了PG_MODULE_MAGIC宏，但 Windows 下有时需要显式定义这个宏来确保导出的Pg_magic_func符号被正确生成。如果后续加载 DLL 时报 magic block 相关的错误，优先检查这一项。

4.2 链接阶段最绕不开的 postgres.lib

编译 zhparser.c 能通过，只代表语法层面过了；链接阶段才是真正考察环境细节的地方。zhparser 调用了 PostgreSQL 提供的很多内部函数，比如palloc、MemoryContextAlloc、DirectFunctionCall1等，这些函数在 PostgreSQL 主程序的导出库 postgres.lib 里。Windows 下链接 DLL 时，必须把这个 lib 文件显式告诉链接器。

在 VS2008 工程的"配置属性 → 链接器 → 输入 → 附加依赖项"中填写：

postgres.lib scws.lib ws2_32.lib

其中 postgres.lib 位于 PostgreSQL 安装目录的 lib 子目录下，scws.lib 就是上一步编译 SCWS 静态库的产物。ws2_32.lib 是 Windows 的 Winsock 库，SCWS 的某些文件或 zhparser 的代码可能间接引用到 socket 相关函数，加上它有备无患。

一个常见问题是直接把C:\Program Files\PostgreSQL\9.6\lib写进了"附加库目录"，却忘了填库文件名。VS2008 的链接机制是附加库目录负责搜索路径，附加依赖项负责具体文件名，两者缺一不可。对应到图形界面里有两处设置，请确保都配置到位。链接结束后，工程输出目录下的 zhparser.dll 就是目标文件。

4.3 配套安装文件：control 与 SQL 脚本一个都不能少

拿到 zhparser.dll 只是第一步，PostgreSQL 要识别这个扩展，还需要两个配套文件：zhparser.control和zhparser--1.0.sql。前者描述扩展元数据，后者定义了扩展里暴露给数据库的对象（比如 parser、函数等）。这两个文件必须和 DLL 配合使用，缺了任何一个，CREATE EXTENSION都会失败。

zhparser.control文件的内容基本如下：

comment = 'Chinese text segmentation' default_version = '1.0' module_pathname = '$libdir/zhparser' relocatable = true

module_pathname里的$libdir是 PostgreSQL 内置宏，运行时会替换成实际的 lib 目录。relocatable = true表示扩展对象不绑定特定 schema，安装时更灵活。zhparser--1.0.sql文件里主要创建扩展所需的函数、parser 定义和操作符映射。实际内容以你拿到的 zhparser 版本源码中的 sql 文件为准，不需要手写，直接拷贝过来修改一下编码即可。

把三件套放到目标位置，命令如下：

copy /y output\zhparser.dll "C:\Program Files\PostgreSQL\9.6\lib\" mkdir "C:\Program Files\PostgreSQL\9.6\share\extension\" copy /y zhparser.control "C:\Program Files\PostgreSQL\9.6\share\extension\" copy /y zhparser--1.0.sql "C:\Program Files\PostgreSQL\9.6\share\extension\"

注意 DLL 是放到lib目录，而 control 和 sql 文件是放到share\extension目录，这两个路径不要搞反。顺手把 SCWS 的词典文件（如 dict.utf8.xdb）也拷到 PostgreSQL 安装目录下，比如放到share\zhparser\子目录，稍后配置分词时会用到。

5. 安装配置避坑：从 CREATE EXTENSION 到第一次中文分词

5.1 现象一：CREATE EXTENSION 报 has no installation script

扩展文件都放好了，执行CREATE EXTENSION zhparser;时却提示extension "zhparser" has no installation script。原因通常是文件命名不匹配，PostgreSQL 对扩展安装脚本的文件名有严格约定：扩展名--版本号.sql。如果你手里的版本号是 1.0，而 sql 文件被命名成zhparser.sql，或者 control 文件里写的是default_version = '2.0'，但目录下只有zhparser--1.0.sql，都会触发这个错误。

解决方法是先检查 control 文件里的版本号，再核对share\extension目录下的文件名是否严格对齐。比如控制文件写的是 1.0，sql 文件就必须叫zhparser--1.0.sql。另外还要注意文件名不能是zhparser--1.0.sql.txt，Windows 默认隐藏扩展名容易让人产生错觉，在 cmd 里用dir确认真实文件名。

5.2 现象二：扩展装上了，分词结果却按单字切

CREATE EXTENSION执行成功，但调用分词函数后返回的全是单个汉字，连词完全没生效。这个现象非常典型，背后的原因是 SCWS 的词典没有成功加载。zhparser 在运行时需要找到 SCWS 的 xdb 词典文件，找不到时会退化成逐字切分，这属于 co 行为而不报错。

解决思路是确认词典文件的路径是否在 zhparser 的可查找范围内。通常做法是把 xdb 文件放到 PostgreSQL 的share目录下，并检查源码里词典路径的编译期配置。如果源码中写死了 Linux 下的路径，就需要在 zhparser.c 里定位到加载词典的代码，改成 Windows 路径后重新编译。这一步在多个 zhparser 版本中处理方式略有差异，有的版本支持运行时通过配置参数指定，有的必须在编译期确定。无论如何，判断标准只有一个：分词结果里出现长度大于 1 的词，就说明词典生效了。

5.3 现象三：加载 DLL 时提示 library is not a valid PostgreSQL library

这个报错通常出现在 DLL 编译完成后替换旧版本，或者 PostgreSQL 升级之后。错误信息里的关键词是 invalid library、magic block 相关的字样。原因有两类：一是 DLL 内嵌的版本宏和当前 PostgreSQL 不一致，二是编译器的 C 运行库与 PostgreSQL 主程序不匹配。

处理办法是确认编译器版本选择和 PostgreSQL 主程序的编译工具链一致。如果你用的是 VS2008 编译，但当前 PostgreSQL 主程序用的是 VS2013 之后的工具链编译，二者之间不一定能兼容。这时优先考虑换一台有对应 VS 版本的机器重新编译，而不是试图通过改写宏来绕过。关于这部分我在第 2 章已经给过版本搭配表，这里不再展开，但它是很多人在 Windows 上栽跟头的重灾区。

5.4 现象四：分词时的标点全部被当成普通字符保留

zhparser 本身有控制标点处理方式的参数，常见的有zhparser.punctuation_ignore。安装完成后默认值是 false，意味着标点符号会作为独立 token 出现。如果要让中文分词结果更干净，需要在会话或配置中打开标点过滤。

执行下面的 SQL 打开常用开关：

SET zhparser.punctuation_ignore = true; SET zhparser.seg_with_duality = true; SET zhparser.dict_in_memory = true;

punctuation_ignore = true的作用是丢弃标点 token；seg_with_duality = true打开"双词"模式，让分词器同时输出组合词和分解词，提升召回率；dict_in_memory = true表示把词典加载到内存常驻，避免每次分词都做文件 I/O。这些参数在多长时间内生效取决于你的设置方式，临时 SET 只影响当前会话，要长期生效需要写入 postgresql.conf，或使用ALTER DATABASE绑定到具体数据库。参数确认无误后，再看分词输出里的标点是否被过滤掉，基本能定位到问题根源。

5.5 现象五：SQL 文件复制过去后报编码错误

在 Windows 下用记事本打开 sql 文件再另存为，容易把编码默认存成 ANSI（GBK），或者添加了 BOM 头。PostgreSQL 读取扩展脚本时要求 UTF-8 编码，一旦遇到非法编码字节，会报invalid byte sequence for encoding "UTF8"。

解决办法很简单：用 Notepad++ 或 VS2008 打开 sql 文件，确认编码是"UTF-8 无 BOM"，再保存一遍。顺手提醒，control 文件里面如果有中文注释，同样要注意编码问题。这一步虽然不涉及编译，但排起队来同样费时间，建议从一开始就处理到位。

6. 收尾验证与进阶：让 zhparser 在 Windows 上真正可用

DLL 编译出来、扩展装上去，只完成了工程的一半，另外一半是把中文全文检索真正用起来。首先做基本验证，创建中文分词配置并绑定解析器：

CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = zhparser); ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;

第一条语句创建了一个名为 chinese 的全文检索配置。第二条语句的含义是：对 zhparser 输出的名词、动词、形容词等 token 类型，使用 simple 词典做归一化处理。simple 词典不做词形还原，只统一大小写，对中文来说正合适。接下来用 ts_debug 验证分词效果：

SELECT * FROM ts_debug('chinese', '中文分词测试文本');

如果分词结果里出现"中文"、"分词"这样的多字词，说明 SCWS 词典加载成功；如果每个汉字都是独立 token，立刻回到第 5 章检查词典路径。验证通过后，在业务表上创建 GIN 索引，实测全文检索性能：

CREATE INDEX idx_doc_content ON document USING gin (to_tsvector('chinese', content));

这里有一点经验供参考：不要直接在查询语句里写to_tsvector('chinese', content)做条件，而应该在数据写入时就生成一个 tsvector 列并建索引，否则每次查询都会重算全部文档的分词，索引形同虚设。常用做法是增加一个content_tsv生成列，用触发器或生成列表达式维护，查询时直接走这个字段。

进阶一步，可以给中文检索加权重。比如标题比正文重要，可以用setweight做加权合并：

SELECT setweight(to_tsvector('chinese', title), 'A') || setweight(to_tsvector('chinese', body), 'B') FROM post;

||操作符合并两组 tsvector，A 权重比 B 高，排序时带权重的词命中排在更前面。配合ts_rank函数做排序，中文搜索体验会明显提升。文本内容较长时，建议设置zhparser的multi_shortest等参数来控制切分粒度，避免生成的 tsvector 过大。

最后补一句我在 Windows 上折腾 zhparser 的教训：拿到源码第一反应不是开 IDE，而是先看它 link 了哪些库、依赖哪些系统接口。把这两件事调查清楚，再动手编译，省下的时间远超多花的那点调查时间。希望这篇笔记能让你在 Windows + VS2008 环境下跑通 zhparser 的路更顺一些。

本文还有配套的精品资源，点击获取