pgvector Windows 编译完整指南：在 Windows 上编译安装 Postgres 向量搜索扩展

pgvector Windows 编译完整指南在 Windows 上编译安装 Postgres 向量搜索扩展【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvectorpgvector 是 PostgreSQL 的向量相似性搜索扩展提供向量类型与 HNSW、IVFFlat 索引。本文只处理一件事在 Windows 上从零编译安装 pgvector 0.8.6 的完整流程以及每一步会遇到的报错修复。文中所有命令均针对 v0.8.6 标签验证PostgreSQL 版本、安装路径若与你不同文中对应位置会标注。先看成功的样子全流程收敛后就是下面 6 行命令按顺序执行完再用 3 条验收命令确认git clone https://gitcode.com/GitHub_Trending/pg/pgvector cd pgvector git checkout v0.8.6 set PGROOTC:\Program Files\PostgreSQL\18 nmake /F Makefile.win nmake /F Makefile.win install验收前两条查文件第三条查扩展实际加载的版本dir %PGROOT%\lib\vector.dll dir %PGROOT%\share\extension\vector.control %PGROOT%\bin\psql -U postgres -c SELECT extversion FROM pg_extension WHERE extname vector前两条应各列出一个文件第三条返回0.8.6。判断整条流程做对了的标志lib下有vector.dllSQL 查询返回的版本号与vector.control里的default_version一致。开工前自检以下检查在x64 Native Tools Command Prompt for VS 2022Visual Studio 2022 安装时勾选使用 C 的桌面开发工作负载中执行。三项全过编译本身基本没有悬念。检查项检查命令期望输出MSVC 编译器clMicrosoft (R) C/C Optimizing Compiler for x64, Version 19.4xPG 头文件与库dir %PGROOT%\include\server\postgres.hdir %PGROOT%\lib\postgres.lib两个文件都被列出不出现 File Not FoundPGROOT 变量set PGROOT显示(变量 PGROOT 未设置)可以接受第 2 步会设若已设置必须是真实的 PG 根目录注意cl不带参数只打印版本信息后退出不会启动编译会话。判断自检做对了的标志cl报出 19.4x 版本号两条dir都能列出对应文件。按关卡推进第 1 关拉取源码并固定到 v0.8.6目的拿到与本文所有行号、版本号一致的源码树。仓库克隆使用 GitCode 镜像地址国内直连更稳定克隆仅需此处使用git clone https://gitcode.com/GitHub_Trending/pg/pgvector cd pgvector git checkout v0.8.6成功标志目录下有Makefile.win和vector.control后者第一行是default_version 0.8.6。岔路git checkout v0.8.6报标签不存在先用git tag --list v0.8*看远端实际有哪些标签克隆自第三方镜像且对不上版本时按上面的地址重新克隆。目录里已有旧源码树不想重克隆执行git fetch git checkout v0.8.6再核对vector.control即可。第 2 关设置 PGROOT目的告诉 nmake PostgreSQL 装在哪。Windows 的Makefile.win不用pg_config定位 PGv0.8.6 的Makefile.win第 23 行留有 TODO 注释头文件目录、库目录全部由PGROOT推导所以这个变量是全流程唯一的单点。在与 nmake 同一个窗口里设置并验证两个关键文件set PGROOTC:\Program Files\PostgreSQL\18 dir %PGROOT%\include\server\postgres.h dir %PGROOT%\lib\postgres.lib成功标志两条dir都列出文件。岔路set只对当前窗口生效换窗口要重设想一劳永逸就写进系统环境变量然后重开窗口。版本号必须与实装一致装的是 PG 17 就写C:\Program Files\PostgreSQL\17不要照抄示例里的 18。第 3 关nmake 编译目的把src/下 18 个 C 文件编译链接成vector.dll。v0.8.6 的Makefile.win里编译规则在第 52–53 行链接规则在第 55–56 行。nmake /F Makefile.win成功标志输出末尾出现vector.dll的链接行工程目录生成vector.dll附带vector.lib、vector.exp全程没有fatal error和LNK20xx。补充两点与 Postgres 16 的 MSVC 编译警告在 0.7.3 已修复见仓库CHANGELOG.md编译 0.8.6 不会遇到nmake没有并行参数几十行编译日志就是全部耗时不必折腾。岔路fatal error C1083: Cannot open include file: postgres.hPGROOT 指错了目录跳到下方故障诊断卡 3。error C2196: case value 4 already used没用 x64 Native Tools 命令行执行nmake /F Makefile.win clean后换正确窗口重跑。与 Linux 的差异Linux/macOS 上对应步骤是一条make构建系统通过pg_config自动找到 PG 的头文件与库Windows 的Makefile.win没有pg_config可用PGROOT就是全部依据——这也是 Windows 流程比 Linux 多出的主要心智负担。若目标机器支持 AVX2可在Makefile.win第 13 行的OPTFLAGS里加/arch:AVX2但产物只能装到同样支持 AVX2 的机器上。第 4 关nmake 安装目的把产物拷进 PostgreSQL 安装目录。v0.8.6 的install目标Makefile.win第 61–66 行做三件事vector.dll进lib.control与全部vector--*.sql进share\extension三个头文件进include\server\extension\vector。以管理员身份运行命令窗口PostgreSQL 服务在运行时先停掉避免文件被占用net stop postgresql-x64-18 nmake /F Makefile.win install net start postgresql-x64-18成功标志输出里vector.dll、vector.control、vector--*.sql的copy均返回 1没有Access is denied。岔路Access is denied窗口没以管理员运行或服务没停干净两项各查一次。SQL 文件复制报找不到文件第 3 关没完成先回去确认vector.dll已生成。判断四个关卡全部做对的标志编译零错误、vector.dll已生成、安装拷贝完整结束且窗口里没有任何红色报错残留。故障诊断卡按遇到概率从高到低排列每张卡固定四行症状、原因、处方、验证。PGROOT 没设会报什么错症状nmake第一行就停!error PGROOT is not set对应 v0.8.6Makefile.win第 24 行的!ifndef检查。原因跑 nmake 的窗口没设 PGROOT或你在另一个窗口里设过。处方在 nmake 所在窗口执行set PGROOTC:\Program Files\PostgreSQL\18。验证echo %PGROOT%打印出路径重跑nmake /F Makefile.win越过版本检查。cl.exe 找不到的修复症状cl is not an internal or external command或The system cannot find the path specified。原因用的是普通 cmd 或 PowerShellMSVC 工具链不在 PATH 上。处方换到 x64 Native Tools Command Prompt for VS 2022必须留在普通窗口时先执行call C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars64.bat。验证cl报出19.4x版本号。C1083: Cannot open include file: postgres.h 的修复症状fatal error C1083: Cannot open include file: postgres.h: No such file or directory。原因PGROOT 指向的目录里没有include\server\postgres.h——装的是别的 PG 版本或安装时没勾 Server 组件。处方改对 PGROOT 里的版本号文件确实不存在就修复 PostgreSQL 安装并勾选 Server 组件。验证dir %PGROOT%\include\server\postgres.h列出该文件编译继续。C2196: case value 4 already used症状error C2196: case value 4 already used等一串 Linux 上不出现的诡异错误。原因用了 x8632 位或混合架构的命令行环境。处方换 x64 Native Tools 命令行nmake /F Makefile.win clean重新编译。验证全程无 C2196vector.dll生成。安装时报 Access is denied症状nmake /F Makefile.win install的copy步骤报Access is denied或文件被另一进程占用。原因窗口没有管理员权限或运行中的服务占着vector.dll。处方窗口以管理员运行net stop postgresql-x64-18安装net start postgresql-x64-18。验证install 输出无报错文件验收三条dir全部命中。LNK2019 无法解析的外部符号症状链接阶段报LNK2019: unresolved external symbol提示涉及postgres.lib。原因%PGROOT%\lib\postgres.lib不存在安装异常。处方修复 PostgreSQL 安装确认该文件存在。验证链接阶段走通vector.dll生成。判断处方有效的标志执行后对应卡的验证一行通过就能从原关卡继续不必从头再来。装完后的验收分三层文件、扩展、查询路径。文件层确认三类产物都到了位dir %PGROOT%\lib\vector.dll dir %PGROOT%\share\extension\vector.control dir %PGROOT%\share\extension\vector--0.8.6.sql扩展层加载并确认版本CREATE EXTENSION IF NOT EXISTS vector; SELECT extversion FROM pg_extension WHERE extname vector;期望返回0.8.6。查询层最小功能测试向量列 HNSW 索引 最近邻查询计划里应走索引CREATE TABLE items (id int PRIMARY KEY, embedding vector(3)); INSERT INTO items VALUES (1, [1,2,3]), (2, [4,5,6]), (3, [1,1,1]); CREATE INDEX items_embedding_hnsw ON items USING hnsw (embedding vector_l2_ops); SET enable_seqscan off; EXPLAIN (COSTS OFF) SELECT id FROM items ORDER BY embedding - [1,2,1] LIMIT 1;期望输出单行Index Scan using items_embedding_hnsw on items。想推倒重来psql 里DROP EXTENSION vector;命令行执行nmake /F Makefile.win uninstallv0.8.6Makefile.win第 71–76 行移除已安装文件。判断验收做对的标志EXPLAIN 里出现Index Scan using items_embedding_hnsw——扩展可用而不只是装上了。收尾cl报出 Version 19.4x 的编译器postgres.h与postgres.lib两条dir检查通过git checkout v0.8.6成功vector.control为 0.8.6nmake /F Makefile.win无 fatal 错误并生成vector.dllinstall 产物齐备lib\vector.dll、share\extension\vector.control、vector--*.sqlCREATE EXTENSION vector成功且extversion为 0.8.6最近邻查询的 EXPLAIN 显示 HNSW 索引扫描以上全部勾掉即本次安装完成。后续版本变动看仓库根目录的CHANGELOG.md构建细节看README.md的 Building 章节与src/源码无法自行解决的问题可到该项目的 issue 页提交即开头克隆地址对应的项目。判断本次安装真正完成的标志上述清单可重复执行、全部复现。【免费下载链接】pgvectorOpen-source vector similarity search for Postgres项目地址: https://gitcode.com/GitHub_Trending/pg/pgvector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考