Windows 环境 PostgreSQL 18 安装与 pgvector 向量扩展部署文档

📃个人主页：编程的一拳超人

⛺️ 欢迎关注：👍点赞 👂🏽留言 😍收藏 💞 💞 💞

于高山之巅，方见大河奔涌；于群峰之上，更觉长风浩荡。 ——《人民日报》

Windows 环境 PostgreSQL 18 安装与 pgvector 向量扩展部署文档

一、环境说明

项说明
操作系统Windows 10 / Windows 11 64 位
PostgreSQL 版本18.x（本文以 18.4 正式版为例）
pgvector 版本v0.8.2（兼容 PostgreSQL 18 的最低版本为 0.8.0）
安装根路径D:\develop_tools\PostgreSQL
依赖说明源码编译方式需提前安装 Visual Studio 2022（勾选「使用 C++ 的桌面开发」工作负荷）

二、PostgreSQL 18 安装

2.1 下载安装包

  1. 访问 PostgreSQL 官方下载页，进入 Windows 安装程序专区，找到 EDB 官方认证的安装包入口。

  1. 进入 EDB 发行版下载列表后，找到PostgreSQL 18.4版本行，点击对应Windows x86-64列的下载按钮，获取 64 位官方交互式安装包。

在这里插入图片描述

2.2 安装步骤

  1. 右键运行下载的安装程序，点击「Next」进入安装向导。
  2. 选择安装目录：修改为D:\develop_tools\PostgreSQL，点击「Next」。
  3. 选择组件：保持默认勾选（PostgreSQL Server、pgAdmin 4、Stack Builder、Command Line Tools），点击「Next」。
  4. 设置数据目录：可保持默认（D:\develop_tools\PostgreSQL\data），点击「Next」。
  5. 设置超级用户密码：设置postgres管理员账号的密码，务必牢记，点击「Next」。
  6. 设置端口：默认 5432，无特殊需求不修改，点击「Next」。
  7. 设置区域语言：默认即可，点击「Next」→ 点击「Next」开始安装。
  8. 安装完成后，取消勾选「Launch Stack Builder」，点击「Finish」结束。

2.3 安装验证

安装完成后，D:\develop_tools\PostgreSQL根目录结构如下，包含运行所需的全部核心目录：


可通过命令行进一步验证版本：

  1. 打开 Windows 命令提示符，进入 PostgreSQL 命令目录：
    cd D:\develop_tools\PostgreSQL\bin psql --version
  2. 正常输出版本号psql (PostgreSQL) 18.4即安装成功。
  3. 打开 Windows 服务列表（services.msc），确认postgresql-x64-18服务处于「正在运行」状态。

三、数据库初始化与基础配置

3.1 服务管理

  • 启动服务：net start postgresql-x64-18
  • 停止服务：net stop postgresql-x64-18
  • 也可通过 Windows 服务面板图形化管理。

3.2 首次连接数据库

方式1：pgAdmin 4 图形化连接
  1. 从开始菜单或安装目录下的pgAdmin 4文件夹启动程序，首次打开设置主密码。
  2. 左侧服务器列表中，默认已创建本地实例，点击后输入postgres账号密码即可连接。
方式2：psql 命令行连接
cd D:\develop_tools\PostgreSQL\bin psql -U postgres

输入密码后进入 SQL 交互终端，出现postgres=#提示符即连接成功。

3.3 创建业务数据库

在 psql 或 pgAdmin 查询窗口执行以下 SQL，创建专门用于向量业务的数据库：

-- 创建向量数据库CREATEDATABASEvectordb;-- 切换到目标数据库（psql 命令行专用）\c vectordb

四、pgvector 向量扩展安装

重要说明：pgvector 为第三方开源向量扩展，PostgreSQL 官方 Stack Builder 默认未收录，无法通过 Stack Builder 一键安装。

Stack Builder 程序位于安装目录的bin文件夹中，文件名为stackbuilder.exe：

打开后展开「Spatial Extensions」分类，可以看到仅内置 PostGIS 空间扩展，没有 pgvector 向量扩展，因此无法通过该工具直接安装：

以下提供两种适配 Windows 环境的部署方案。

方案一：源码编译安装（推荐）

前置条件

已安装 Visual Studio 2022（Community/Professional 均可），且勾选「使用 C++ 的桌面开发」工作负荷。可在系统程序列表中确认安装状态：

操作步骤
  1. 在开始菜单搜索「x64 Native Tools Command Prompt for VS 2022」，右键选择「以管理员身份运行」。
  2. 设置 PostgreSQL 安装路径环境变量：
    set "PGROOT=D:\develop_tools\PostgreSQL"
  3. 拉取 pgvector 稳定版源码：
    cd %TEMP% git clone --branch v0.8.2 https://github.com/pgvector/pgvector.git cd pgvector
  4. 编译并自动安装：
    :: 编译64位版本 nmake /F Makefile.win :: 自动部署到 PostgreSQL 对应目录 nmake /F Makefile.win install
  5. 部署完成后，可在以下路径确认文件：
    • 动态库：D:\develop_tools\PostgreSQL\lib\vector.dll
    • 扩展文件：D:\develop_tools\PostgreSQL\share\extension\vector.control
    • 安装脚本：D:\develop_tools\PostgreSQL\share\extension\vector--0.8.2.sql

方案二：手动部署预编译包（无需编译，快速上手）

适用于未安装 Visual Studio 的场景，直接将编译好的文件复制到对应目录。

  1. 下载匹配PostgreSQL 18 + Windows x64的 pgvector 预编译包（版本必须 ≥ 0.8.0）。
  2. 解压后得到 3 个核心文件：vector.dll、vector.control、vector--0.8.2.sql。
  3. 按以下路径复制文件：
    • 将vector.dll复制到D:\develop_tools\PostgreSQL\lib\目录
    • 将vector.control和vector--0.8.2.sql复制到D:\develop_tools\PostgreSQL\share\extension\目录

五、扩展启用与功能验证

5.1 启用向量扩展

pgvector 为数据库级扩展，每个需要使用向量功能的数据库都需要单独执行启用操作。

-- 切换到目标数据库（如 vectordb）\c vectordb-- 启用向量扩展CREATEEXTENSIONIFNOTEXISTSvector;

5.2 验证安装

执行以下 SQL 查看扩展版本：

SELECTextname,extversionFROMpg_extensionWHEREextname='vector';

返回结果包含vector与版本号0.8.2，即安装启用成功。

5.3 基础使用示例

1. 创建带向量字段的表
CREATETABLEdocuments(id bigserialPRIMARYKEY,contenttext,embedding vector(3)-- 括号内为向量维度，需与嵌入模型输出维度一致);
2. 插入向量数据
INSERTINTOdocuments(content,embedding)VALUES('技术文档A','[1, 2, 3]'),('技术文档B','[2, 3, 4]'),('产品文档C','[0, 1, 2]');
3. 向量相似度查询
-- 欧氏距离查询：返回与目标向量最相似的前 2 条SELECTid,content,embedding<->'[1,2,3]'ASdistanceFROMdocumentsORDERBYdistanceLIMIT2;-- 其他距离算子-- <#> ：负内积距离-- <=> ：余弦距离
4. 创建向量索引（数据量 >1 万条时推荐）
-- HNSW 索引：高性能、高精度，生产环境推荐CREATEINDEXONdocumentsUSINGhnsw(embedding vector_l2_ops);-- IVFFlat 索引：内存占用小、构建快，适合中等数据量CREATEINDEXONdocumentsUSINGivfflat(embedding vector_l2_ops)WITH(lists=100);

六、常见问题排查

  1. Stack Builder 中找不到 pgvector
    属于正常现象，pgvector 未纳入 EDB 官方 Stack Builder 软件源，请使用本文的源码编译或手动部署方案。

  2. 执行CREATE EXTENSION报错「could not access file “vector”」
    检查vector.dll是否放入正确的lib目录，确认 pgvector 版本与 PostgreSQL 18 匹配（必须 ≥0.8.0）。

  3. 源码编译报错

    • 确认使用的是「x64 Native Tools Command Prompt」，而非普通 cmd。
    • 确认PGROOT路径与实际安装路径完全一致。
    • 必须以管理员身份运行命令行，避免权限不足导致写入失败。

  4. 索引构建缓慢或失败
    构建索引前临时调大维护内存参数：

    SETmaintenance_work_mem='256MB';

七、核心注意事项

  1. 版本强匹配：仅 pgvector 0.8.0 及以上版本支持 PostgreSQL 18，低版本会加载失败。
  2. 扩展作用域：pgvector 是数据库级扩展，新建数据库需重新执行CREATE EXTENSION。
  3. 无需预加载：pgvector 不需要修改postgresql.conf的shared_preload_libraries参数，安装后直接启用即可使用。