pgvector实战：攻克Windows平台编译难题的完整解决方案

2026-04-19 09:06:54作者：钟日瑜

问题现象：Windows编译的双重挑战

在Windows 11系统环境下编译pgvector扩展时，开发者通常会遭遇两类阻碍编译进程的问题。这些问题不仅影响开发效率，也阻碍了PostgreSQL向量搜索功能在Windows平台的应用。

dllexport重复定义警告

编译过程中首先出现的是一系列警告信息，虽然不会直接中断编译，但暗示了潜在的符号冲突风险：

src\bitvec.c(43): warning C4141: 'dllexport': used more than once
src\hnsw.c(190): warning C4141: 'dllexport': used more than once
src\vector.c(567): warning C4141: 'dllexport': used more than once

这些警告表明多个源文件中存在对同一符号的重复导出声明，可能导致运行时的符号解析错误。

tupmacs.h头文件致命错误

更为严重的是来自PostgreSQL头文件的编译错误，直接导致编译过程中断：

C:\Program Files\PostgreSQL\16\include\server\access/tupmacs.h(65): error C2196: case value '4' already used
C:\Program Files\PostgreSQL\16\include\server\access/tupmacs.h(197): error C2196: case value '4' already used
NMAKE : fatal error U1077: '"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.34.31933\bin\HostX64\x64\cl.exe"' : return code '0x2'
Stop.

这类错误发生在PostgreSQL内部头文件中，通常与编译器环境配置密切相关。

环境排查：定位问题根源

🔍 编译器架构检查

Windows平台编译pgvector时，首先需要确认使用的是64位编译器环境：

echo %VSCMD_ARG_TGT_ARCH%

正确输出应为x64，而非x86。若显示为x86，表明当前使用的是32位编译环境，这是导致tupmacs.h错误的主要原因。

🔍 PostgreSQL安装验证

执行以下命令检查PostgreSQL安装版本和架构：

psql --version

输出应包含64-bit字样，例如：psql (PostgreSQL) 16.1 (64-bit)。32位版本的PostgreSQL与64位编译器环境不兼容，会直接导致编译错误。

🔍 环境变量检查

验证关键环境变量配置：

echo %PGSQL_DIR%
echo %PATH% | findstr /i postgres

确保PGSQL_DIR指向正确的PostgreSQL安装目录，且PATH中包含PostgreSQL的bin目录。

问题复现步骤：从零构建问题环境

要复现上述编译问题，可按以下步骤操作：

安装32位Visual Studio组件
- 通过Visual Studio Installer安装"Desktop development with C++"
- 确保勾选了"MSVC v143 - VS 2022 C++ x86/x64 build tools"

配置32位编译环境

"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars32.bat"

获取pgvector源码

git clone https://gitcode.com/GitHub_Trending/pg/pgvector
cd pgvector

尝试编译
```
nmake /F Makefile.win
```

执行上述步骤后，系统将重现dllexport警告和tupmacs.h错误，为后续解决方案验证提供环境。

深层原理：错误背后的技术解析

Datum类型系统冲突

PostgreSQL使用Datum类型作为通用数据容器，其大小由SIZEOF_DATUM宏定义。在64位系统中，SIZEOF_DATUM应为8字节，而32位环境下为4字节。tupmacs.h头文件中包含基于此宏的条件编译：

#if SIZEOF_DATUM == 8
    case 8:
        ...
#elif SIZEOF_DATUM == 4
    case 4:
        ...
#endif

当编译器环境为32位而PostgreSQL为64位时，SIZEOF_DATUM宏定义与实际编译环境不匹配，导致case值重复定义错误。

Windows符号导出机制

Windows平台使用__declspec(dllexport)标记需要导出的函数。pgvector早期版本中，部分函数在头文件和源文件中同时使用了该标记，导致MSVC编译器产生C4141警告：

// 在头文件中
__declspec(dllexport) Datum vector_add(PG_FUNCTION_ARGS);

// 在源文件中
__declspec(dllexport) Datum vector_add(PG_FUNCTION_ARGS) {
    ...
}

这种重复导出声明虽然不影响GCC编译，但在MSVC环境下会产生警告。

分步方案：完整解决编译问题

🛠️ 环境准备与配置

安装64位编译工具
- 确保Visual Studio安装了"MSVC v143 - VS 2022 C++ x64/x86 build tools"
- 安装Windows SDK (版本应与PostgreSQL编译时使用的版本匹配)

配置64位编译环境

"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat"

验证环境配置
```
cl.exe | findstr /i "64-bit"
```

🛠️ 源码调整

克隆最新版pgvector

git clone https://gitcode.com/GitHub_Trending/pg/pgvector
cd pgvector

修改头文件导出声明 若使用的版本仍存在dllexport重复定义问题，需修改相关头文件：

// src/vector.h
// 将
__declspec(dllexport) Datum vector_add(PG_FUNCTION_ARGS);
// 修改为
Datum vector_add(PG_FUNCTION_ARGS);

检查Makefile.win配置 确保Makefile.win中包含正确的PostgreSQL路径：
```
PGSQL_DIR = C:\Program Files\PostgreSQL\16
```

🛠️ 编译与安装

执行编译

nmake /F Makefile.win clean
nmake /F Makefile.win

安装扩展
```
nmake /F Makefile.win install
```

验证安装

dir "%PGSQL_DIR%\share\extension\vector*"

验证方法：确保扩展正常工作

✅ 数据库集成测试

启用pgvector扩展
```
CREATE EXTENSION vector;
```

创建测试表

CREATE TABLE items (
    id SERIAL PRIMARY KEY,
    embedding vector(3)
);

插入测试数据

INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]');

执行向量查询

SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 1;

若查询返回结果且无错误，表明pgvector已成功编译并正常工作。

✅ 功能完整性验证

执行扩展提供的核心功能测试：

-- 向量运算测试
SELECT '[1,2,3]'::vector + '[4,5,6]'::vector;

-- 距离计算测试
SELECT '[1,2,3]'::vector <-> '[4,5,6]'::vector;

-- 索引功能测试
CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops);