企业官网建设流程全解析

pgvector Windows 编译实战：3 步 nmake 构建，7 类典型报错按阶段排查

【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvector

pgvector 是 Postgres 的向量相似度检索扩展。本文以 Windows 为平台，讲清在 Visual Studio + nmake 工具链下本地编译并安装 vector.dll 的全过程：开工前要核对什么、从拉取源码到安装只需哪三条命令、遇到每类真实报错如何定位修复，最后给出一次可执行的相似度查询验收。

开工前核对 5 项前置条件

编译失败大多出在前置环境，而不是编译命令本身。按下面这份清单逐项验证，通过后再动手：

其中PGROOT是给编译器的一块“路牌”：Makefile.win 里所有头文件、库文件和安装目标目录，都以它作为根（第 27–32 行），指错一层，后面连环报错。

用 3 步完成获取、编译、安装

以下命令均在该管理员原生命令提示符中执行。

第 1 步：获取源码并设置 PGROOT

set "PGROOT=C:\Program Files\PostgreSQL\16" cd %TEMP% git clone --branch v0.8.6 https://gitcode.com/GitHub_Trending/pg/pgvector.git cd pgvector

验收：dir Makefile.win vector.control两个文件都在；echo %PGROOT%与上面 set 的值一致。注意set只作用于当前窗口，换窗口要重新设置。

第 2 步：编译

nmake /F Makefile.win

✅ 验收：源码根目录生成vector.dll、vector.lib，以及sql\vector--0.8.6.sql（版本号随你 clone 的标签变化）。

第 3 步：安装

nmake /F Makefile.win install

install 目标（Makefile.win 第 61–66 行）会把vector.dll拷入%PGROOT%\lib，把vector.control和各版本升级 SQL 拷入%PGROOT%\share\extension。

✅ 验收：

dir "%PGROOT%\lib\vector.dll" dir "%PGROOT%\share\extension\vector.control"

两条都有文件记录即安装落位。

按失败阶段排查 7 类典型报错

3.1 环境阶段：nmake 报 PGROOT is not set

症状：nmake 刚启动就输出!error PGROOT is not set（对应 Makefile.win 第 25 行），一条源文件都没编译。

原因：当前窗口没设置 PGROOT。

修复：在同一个窗口内重新set "PGROOT=..."并用echo验证。若设置后仍报同样错误，说明路径层级指错——正确指向是...\PostgreSQL\16这一层，再高一层（...\PostgreSQL）就取不到include\server。

3.2 编译阶段：'cl.exe' 不是内部或外部命令

症状：第一个编译任务即报'cl.exe' is not recognized as an internal or external command。

原因：当前终端没有加载编译器环境。

修复：从开始菜单改用x64 Native Tools Command Prompt for VS 2022（管理员）；必须沿用普通提示符时，先执行一次：

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

3.3 编译阶段：Cannot open include file: 'postgres.h'

症状：C1083: Cannot open include file: 'postgres.h': No such file or directory。

原因：PGROOT 指向错误，或 PostgreSQL 安装缺少头文件目录。

修复：执行dir "%PGROOT%\include\server\postgres.h"确认存在；不存在则重新安装该版本 PostgreSQL（Windows 标准安装包默认含头文件）。

3.4 编译阶段：error C2196: case value '4' already used

症状：编译中途报error C2196: case value '4' already used。

原因：架构不匹配——实际不在 x64 环境中编译（如误开了 x86 Native Tools 提示符）。

修复：换用x64 Native Tools Command Prompt，先清理再重编，避免残留中间产物干扰：

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

3.5 链接阶段：LNK2019 无法解析的外部符号

症状：源文件全部编译通过，最后链接 DLL 时报LNK2019: unresolved external symbol float_to_shortest_decimal_bufn。

原因：Postgres 17.0–17.2 的已知缺陷，postgres.lib 未导出该符号。

修复：把本机 PostgreSQL 升到 17.3 及以上再重新编译。若 LNK2019 报的是其它符号，先执行dir "%PGROOT%\lib\postgres.lib"，确认 PGROOT 指向的确实是当前在用的那套 Postgres 安装。

3.6 安装阶段：copy 时 Access is denied

症状：install 目标的某条copy语句报Access is denied。

原因：对%PGROOT%\lib没有写权限（默认安装在 Program Files 下）。

修复：改用管理员提示符重跑nmake /F Makefile.win install；若个别文件被服务占用，先net stop postgresql-x64-16，安装完成后net start postgresql-x64-16恢复。

3.7 加载阶段：CREATE EXTENSION vector 找不到 control 文件

症状：ERROR: could not open extension control file ".../vector.control": No such file or directory。

原因：install 没跑完，或 control 文件没落到%PGROOT%\share\extension。

修复：按 2.3 的两条dir命令复核产物，缺哪个补哪一步；文件齐备后，确认CREATE EXTENSION vector是在目标数据库会话里执行的——DLL 只装一次，但每个要用到的库都要各自启用。

验收：从安装产物到一次真实相似度查询

4.1 确认 vector.dll 安装位置

dir "%PGROOT%\lib\vector.dll" dir "%PGROOT%\share\extension\vector.control"

预期：两条命令均返回文件记录。

4.2 加载扩展并跑通向量相似度查询

用 psql 连入目标数据库：

CREATE EXTENSION vector;

预期返回CREATE EXTENSION。

CREATE TABLE test_vec (id int, embedding vector(3)); INSERT INTO test_vec VALUES (1, '[1,2,3]'), (2, '[10,10,10]'); SELECT id, embedding <-> '[2,1,3]' AS dist FROM test_vec ORDER BY dist ASC LIMIT 1;

✅ 预期：返回1 | 1.414214（向量[1,2,3]到[2,1,3]的欧氏距离为 √2），说明类型、运算符、索引扩展全部生效。

求助入口与可选优化

• 遇到本文未覆盖的报错：完整保存 nmake 输出连同 PostgreSQL 版本号，到 pgvector 项目的 Issue 跟踪器提交，或在 README 的 “Installation Notes - Windows” 一节对照自查。
• 性能相关：Makefile.win 第 17 行默认已带/O2 /fp:fast；若本机 CPU 支持 AVX2，可把第 13 行的OPTFLAGS =填为/arch:AVX2后重编，距离计算会生成更完整的 SIMD 指令；不支持 AVX2 的旧机器不要加该参数。
• 换标签或改参数前，用nmake /F Makefile.win clean清掉全部中间产物，避免旧 .obj 混入新构建。

【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvector