从克隆到跑通：pgvector 向量检索扩展安装教程（约 10 分钟）-平芜编程栈

从克隆到跑通：pgvector 向量检索扩展安装教程（约 10 分钟）

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

pgvector 是 PostgreSQL 的开源向量检索扩展，装好之后 embedding 可以直接躺在普通表里，建个 HNSW 索引、一条ORDER BY就能查相似项，不用再单独养一套向量数据库。这篇文章带你从零走完整个流程：编译安装、启用扩展、建表灌数据、跑通第一条向量查询。全程 4 条编译命令 + 3 条 SQL，跟着敲就行。

开工前核对这 4 项

项目	要求	为什么容易漏
PostgreSQL	13 及以上（推荐 16 / 17）	装好软件还不够，编译时要用到它的头文件
开发头文件	Linux/macOS 装`postgresql-server-dev-<版本>`（Ubuntu/Debian 包名）	只装了服务端没装 dev 包时，`make`会报找不到`pg_config`
编译器	Linux/macOS 用 gcc 或 clang；Windows 用 VS 2019+ 并勾选"C++ 桌面开发"	Windows 少了 SDK 组件会在编译中途才报错
git 和 psql 客户端	任意较新版	拉源码、连库各用一次

不想本地编译的话，仓库自带docker目标，Makefile 里make docker可以直接构建镜像，本文只讲源码编译这条路。

Linux / macOS：4 条命令编译安装 pgvector

1. 把源码拉到临时目录

cd /tmp git clone --branch v0.8.6 https://gitcode.com/GitHub_Trending/pg/pgvector cd pgvector

固定拉 v0.8.6 这个版本，装完源码删掉也不影响。跑完应看到/tmp/pgvector目录出现，里面有src/、sql/、Makefile。

2. make 编译

make

这一步按 Makefile 把 src/ 下的 18 个 C 文件编成vector.so。跑完应生成vector.so，终端没有Error字样即成功。

3. make install 装进 PostgreSQL

make install

这一步把vector.so、vector.control 和 sql/ 下的版本脚本拷进 PostgreSQL 的lib和share/extension目录，普通用户装系统目录时会提示权限不足，加sudo make install即可。跑完后share/extension/下应能看到vector--0.8.6.sql。

4. Windows：把 make 换成 nmake

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

Makefile.win 靠PGROOT定位头文件和安装目标，所以第一条命令必须在同一个会话里先执行，且要在 VS 的"x64 Native Tools Command Prompt"里敲。最后一条命令跑完，%PGROOT%\lib下应出现vector.dll。

启用 vector 扩展：2 条 SQL 验证

用 psql 连上你要用的数据库（注意：每个数据库都要单独启用一次）：

CREATE EXTENSION vector; SELECT vector_version();

第二条应返回0.8.6，看到版本号说明扩展已加载，部署闭环完成。✅

建表、灌数据、跑第一条向量查询

下面 3 条 SQL 是最小验证：建一张 3 维向量表、插两条数据、按 L2 距离查最近邻：

CREATE TABLE items (id bigserial 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 5;

第三条查询的<->是 L2 距离算子。预期返回 2 行，[1,2,3]排在第一、距离约 1.73，因为它离查询向量[3,1,2]更近。

数据量大时给索引加速，加一行：

CREATE INDEX ON items USING hnsw (embedding vector_l2_ops);

建完这条索引，上面的查询就会走 HNSW 图索引（实现在 src/hnsw.c），小表则顺序扫描更快，先跑通再调优。

pgvector 装不动时，对照这张表找原因

⚠️ 编译阶段飘红基本逃不出下面 4 种，先对号入座：

现象	原因	解法
`pg_config: command not found`	缺 PostgreSQL 服务端开发包	装上与服务端同版本的`postgresql-server-dev-<版本>`后重跑`make`
`make install`提示权限不足	目标目录属于系统	换`sudo make install`
`PGROOT is not set`（Windows）	变量没设或重开了终端后失效	当前会话重新执行`set "PGROOT=..."`，再`nmake /F Makefile.win clean`从头编
找不到`crtdefs.h`、大量 C2xxx 错误（Windows）	用错终端，不在 VS 原生环境里	换成"x64 Native Tools Command Prompt"，`nmake /F Makefile.win clean`后重编