简介本资源为适配 PostgreSQL 17 的 PostGIS 3.5.0 安装包面向需要在关系型数据库中处理空间数据的 GIS 开发者、后端工程师及空间分析学习者。PostGIS 作为开源空间数据库扩展实现了 OpenGIS 规范可为 PostgreSQL 增加点、线、面等空间对象类型与空间索引、空间聚合、空间连接等分析能力广泛用于城市规划、交通管理、环境监测与物流配送等场景。压缩包共 1317 个文件约 130.69MB以 933 个 sql 脚本、79 个 dll 动态库、75 个 csv 数据文件及 50 个 tif 栅格影像为主另含 control 扩展定义、json 配置、exe 工具与多种坐标系参数文件覆盖扩展安装、数据导入与坐标转换等环节。目前已有 192 人学习下载适合希望快速搭建空间数据库环境、开展地理空间查询与分析的读者参考使用。1. postgis-bundle-pg17-3.5.0x64.zip 到底是什么一次把 Windows 离线部署讲透如果你在 Windows 上装过 PostGIS大概率经历过这种场景PostgreSQL 17 装好了兴冲冲去跑CREATE EXTENSION postgis;结果报could not open extension control file翻遍 Stack Overflow 发现要自己编译 GEOS、PROJ、GDAL光依赖就能耗掉一整天。postgis-bundle-pg17-3.5.0x64.zip这个包名拆开看就是答案PostGIS 的 bundle 打包版对应 PostgreSQL 17PostGIS 版本 3.5.0x64 架构zip 压缩分发。它把 PostGIS 运行所需的二进制、依赖库、SQL 脚本、扩展控制文件全部预编译好解压即用不需要你碰编译器。这个方案解决的核心问题是在无网络或网络受限的 Windows 机器上把 PostGIS 3.5.0 挂到 PostgreSQL 17 实例上并让空间数据类型、空间索引、坐标转换全部可用。适合三类人一是内网开发环境的数据工程师二是需要在 Windows 本机快速搭空间数据库做验证的后端三是被源码编译反复折磨、只想拿到一个能跑环境的 GIS 从业者。下面按「包结构 → 部署 → 验证 → 排错 → 进阶」的顺序把每一步的参数和坑都摊开讲。2. 拆开 zip 看结构PostGIS bundle 里到底装了什么2.1 目录布局与 PostgreSQL 17 的对应关系拿到 zip 先别急着解压到 PostgreSQL 安装目录先看清楚里面有什么。一个标准的 PostGIS bundle 包解压后通常呈现这样的结构postgis-bundle-pg17-3.5.0x64/ ├── bin/ │ ├── postgis-3.dll │ ├── libgeos.dll / libgeos_c.dll │ ├── libproj.dll │ ├── libgdal.dll │ ├── libjson-c.dll │ ├── libxml2.dll │ └── ...其他运行时依赖 ├── lib/ │ └── postgresql/ │ ├── postgis-3.dll │ └── ...插件形式的扩展库 ├── share/ │ └── extension/ │ ├── postgis.control │ ├── postgis--3.5.0.sql │ ├── postgis_topology.control │ ├── postgis_topology--3.5.0.sql │ ├── postgis_raster.control │ ├── postgis_raster--3.5.0.sql │ └── ...其他扩展的 control 和 sql └── README / LICENSE关键点在于share/extension/下的.control文件和.sql文件是 PostgreSQL 识别扩展的唯一入口。CREATE EXTENSION postgis;执行时PostgreSQL 会去SHARE_DIR/extension/找postgis.control读取里面的directory、default_version、module_pathname等字段然后加载对应的.sql脚本和 DLL。所以部署的本质就是把 bin 下的 DLL 放到 PostgreSQL 能找到的路径把 share/extension 下的文件放到 PostgreSQL 的扩展目录。2.2 三个必须确认的路径参数在动手之前先确认你本机 PostgreSQL 17 的三个路径。打开psql或 pgAdmin执行-- 查看 PostgreSQL 的共享目录和库目录 SHOW shared_preload_libraries; SHOW dynamic_library_path; SELECT name, setting FROM pg_settings WHERE name IN (shared_preload_libraries, dynamic_library_path);更直接的方式是查 PostgreSQL 的安装信息# 在 PostgreSQL 的 bin 目录下执行确认关键路径 pg_config --sharedir # 扩展 control/sql 文件应该放这里 pg_config --libdir # 扩展 DLL 应该放这里 pg_config --bindir # PostgreSQL 可执行文件目录典型输出Windows 默认安装SHAREDIR C:/Program Files/PostgreSQL/17/share LIBDIR C:/Program Files/PostgreSQL/17/lib BINDIR C:/Program Files/PostgreSQL/17/bin这三个路径决定了你解压后文件该往哪放。注意pg_config在 Windows 上可能不在 PATH 里需要写全路径比如C:\Program Files\PostgreSQL\17\bin\pg_config.exe --sharedir。提示如果你的 PostgreSQL 是通过 EDB 安装包安装的pg_config通常位于bin目录下如果是绿色版或解压版路径可能不同以实际安装位置为准。2.3 版本匹配为什么必须是 pg17 配 3.5.0PostGIS 的 DLL 是链接到特定 PostgreSQL 大版本的。PostgreSQL 17 的 ABI应用二进制接口与 16 不兼容用 pg16 编译的 PostGIS DLL 放到 pg17 的 lib 目录下CREATE EXTENSION时会报could not load library或incompatible library version。同理PostGIS 3.5.0 的 SQL 脚本里引用的函数签名和内部 C 函数入口也是针对 3.5.0 这个版本编译的混用 3.4.x 的 control 文件和 3.5.0 的 DLL 同样会出问题。所以包名里的pg17和3.5.0不是装饰是硬约束。部署前用下面这条命令确认 PostgreSQL 版本SELECT version(); -- 输出示例PostgreSQL 17.2, compiled by Visual C build 1942, 64-bit只要大版本是 17小版本17.0/17.1/17.2通常不影响 PostGIS 加载因为 PostgreSQL 的小版本升级保持 ABI 兼容。但如果你是从 16 升级到 17务必重新部署对应 pg17 的 PostGIS bundle不要直接拷贝旧目录。3. 在 Windows 上把 PostGIS 3.5.0 挂到 PostgreSQL 17解压、拷贝、建扩展3.1 解压与文件归位的完整命令假设你把 zip 解压到了D:\postgis-bundle-pg17-3.5.0x64PostgreSQL 安装在默认路径C:\Program Files\PostgreSQL\17。用管理员权限打开 PowerShell 或 CMD按下面的步骤操作。第一步备份原有的 extension 目录如果之前装过 PostGIS 或其他扩展# 以管理员身份运行 cd C:\Program Files\PostgreSQL\17 ren share\extension share\extension_bak mkdir share\extension第二步拷贝 bundle 中的文件到对应目录# 拷贝 DLL 到 lib 目录 xcopy /Y /E D:\postgis-bundle-pg17-3.5.0x64\lib\* C:\Program Files\PostgreSQL\17\lib\ # 拷贝 bin 下的运行时依赖到 PostgreSQL 的 bin 目录 xcopy /Y /E D:\postgis-bundle-pg17-3.5.0x64\bin\* C:\Program Files\PostgreSQL\17\bin\ # 拷贝扩展控制文件和 SQL 脚本 xcopy /Y /E D:\postgis-bundle-pg17-3.5.0x64\share\extension\* C:\Program Files\PostgreSQL\17\share\extension\第三步确认关键文件到位dir C:\Program Files\PostgreSQL\17\share\extension\postgis.control dir C:\Program Files\PostgreSQL\17\lib\postgis-3.dll dir C:\Program Files\PostgreSQL\17\bin\libgeos_c.dll这三条命令分别验证扩展入口、核心库、几何引擎依赖是否就位。如果postgis.control不存在CREATE EXTENSION一定失败如果postgis-3.dll不在 lib 目录加载时会报找不到模块如果libgeos_c.dll缺失即使扩展创建成功执行空间函数时也会崩溃。注意Windows 的 DLL 搜索路径优先从可执行文件所在目录即 PostgreSQL 的 bin 目录加载所以 bin 目录下的依赖 DLL 必须齐全。不要只拷贝 lib 下的文件。3.2 创建扩展从 postgis 到 postgis_raster 的取舍文件就位后重启 PostgreSQL 服务让新的 DLL 生效# 以管理员身份重启服务服务名通常是 postgresql-x64-17 net stop postgresql-x64-17 net start postgresql-x64-17然后连接到目标数据库执行扩展创建-- 连接到你的业务数据库而不是 postgres 默认库 \c your_spatial_db -- 创建核心空间扩展 CREATE EXTENSION postgis; -- 如果需要栅格数据处理 CREATE EXTENSION postgis_raster; -- 如果需要拓扑分析 CREATE EXTENSION postgis_topology; -- 验证安装 SELECT postgis_full_version();postgis_full_version()会输出类似下面的内容POSTGIS3.5.0 3.5.0 [EXTENSION] PGSQL170 GEOS3.12.0-CAPI-1.18.0 PROJ9.3.0 GDALGDAL 3.8.0 LIBXML2.11.5 LIBJSON0.17 RASTER这里要重点看几个字段PGSQL170表示 PostgreSQL 17.0 的扩展接口GEOS是几何运算引擎版本PROJ是坐标转换库版本GDAL是栅格和格式支持库版本。如果postgis_full_version()能正常返回且没有报错说明核心链路已经通了。关于扩展的取舍postgis是必装的提供geometry、geography类型和基础空间函数。postgis_raster只有在你需要处理栅格数据如遥感影像、DEM时才装它会额外加载 GDAL 相关依赖增加内存占用。postgis_topology用于拓扑关系分析一般业务场景用不到。我的习惯是先只装postgis跑通验证后再按需追加避免一次性引入太多依赖导致排错困难。3.3 验证空间能力建表、插数据、走索引扩展创建成功只是第一步真正要确认的是空间索引和坐标转换能不能用。下面这段 SQL 覆盖了建表、插入、空间查询、索引命中四个环节-- 建一张带空间列的表 CREATE TABLE city_points ( id SERIAL PRIMARY KEY, name TEXT, geom GEOMETRY(Point, 4326) ); -- 插入几个测试点北京、上海、广州的经纬度 INSERT INTO city_points (name, geom) VALUES (北京, ST_SetSRID(ST_MakePoint(116.4074, 39.9042), 4326)), (上海, ST_SetSRID(ST_MakePoint(121.4737, 31.2304), 4326)), (广州, ST_SetSRID(ST_MakePoint(113.2644, 23.1291), 4326)); -- 创建空间索引 CREATE INDEX idx_city_points_geom ON city_points USING GIST (geom); -- 查询距离北京 1000 公里内的城市使用 geography 做球面距离计算 SELECT name, ST_Distance(geom::geography, ST_SetSRID(ST_MakePoint(116.4074, 39.9042), 4326)::geography) / 1000 AS distance_km FROM city_points WHERE ST_DWithin(geom::geography, ST_SetSRID(ST_MakePoint(116.4074, 39.9042), 4326)::geography, 1000000) ORDER BY distance_km;这段 SQL 里几个关键点ST_MakePoint构造点几何ST_SetSRID指定坐标系为 4326WGS84 经纬度::geography把几何转成地理类型以便用米为单位做距离计算ST_DWithin利用空间索引做范围过滤。如果这些都能跑通且返回正确结果说明 PostGIS 的几何运算、坐标转换、空间索引三条链路全部正常。再验证一下坐标转换PROJ 库是否工作-- 把 WGS84 经纬度转成 Web MercatorEPSG:3857 SELECT ST_AsText( ST_Transform( ST_SetSRID(ST_MakePoint(116.4074, 39.9042), 4326), 3857 ) ); -- 预期输出类似POINT(12958174.51 4825915.02)如果ST_Transform报transform: couldnt project point或返回空说明 PROJ 的数据文件proj.db没有正确部署。这是 bundle 包部署中最常见的坑之一下一章详细说。4. 部署 PostGIS bundle 时最容易翻车的五个地方4.1 现象CREATE EXTENSION 报 could not open extension control file原因postgis.control没有放到 PostgreSQL 的share/extension目录或者放到了错误的子目录。有些 bundle 包的目录层级多一层比如share/extension/postgis/postgis.control而 PostgreSQL 只认share/extension/postgis.control这一层。解决用pg_config --sharedir确认准确的 SHAREDIR然后检查SHAREDIR/extension/postgis.control是否存在。如果文件在子目录里把它移到上一层。同时确认文件权限Windows 下 PostgreSQL 服务账户通常是NETWORK SERVICE或专用账户需要对该文件有读取权限。4.2 现象could not load library postgis-3.dll或加载后执行函数崩溃原因DLL 依赖链断裂。postgis-3.dll依赖libgeos_c.dll、libproj.dll、libgdal.dll等这些依赖必须位于 Windows 的 DLL 搜索路径中。PostgreSQL 启动时DLL 搜索路径优先是可执行文件所在目录bin其次是系统 PATH。如果只把postgis-3.dll放到 lib 目录而依赖 DLL 放在别处加载就会失败。解决把 bundle 中 bin 目录下的所有 DLL 都拷贝到 PostgreSQL 的 bin 目录。如果仍然报错用 Dependency Walker 或dumpbin /dependents postgis-3.dll查看缺失的依赖逐个补齐。注意不要混用不同来源的 GEOS/PROJ DLL版本不匹配会导致运行时崩溃而非加载失败更难排查。4.3 现象ST_Transform 报错或返回 NULL提示 proj.db 找不到原因PROJ 库需要proj.db数据文件来支持坐标转换。这个文件通常位于share/contrib/postgis-3.5/proj/或类似路径下PROJ 通过环境变量PROJ_LIB或编译时指定的路径查找。bundle 包如果只拷贝了 DLL 而没拷贝 proj 数据目录坐标转换就会失败。解决找到 bundle 中的proj数据目录通常包含proj.db把它拷贝到 PostgreSQL 的share目录下比如C:\Program Files\PostgreSQL\17\share\proj\。然后设置环境变量PROJ_LIB指向该目录或者在 postgresql.conf 中通过SET proj_lib指定。重启服务后再次测试ST_Transform。4.4 现象空间索引创建成功但查询不走索引EXPLAIN 显示 Seq Scan原因空间索引GiST的使用依赖于查询条件和操作符。ST_DWithin、边界框相交等操作符能触发索引而ST_Distance 1000这种写法不会走索引因为ST_Distance是计算函数而非索引操作符。另外如果表数据量太小比如只有几行PostgreSQL 优化器会认为全表扫描更快主动放弃索引。解决用EXPLAIN ANALYZE确认执行计划。确保查询条件使用ST_DWithin或操作符。如果数据量确实小可以临时SET enable_seqscan off;强制走索引来验证索引本身是否可用。生产环境中空间索引的命中还依赖于ANALYZE收集的统计信息建完索引后记得对表执行ANALYZE city_points;。4.5 现象从 pg16 升级到 pg17 后旧数据库的 PostGIS 扩展报版本不匹配原因PostgreSQL 大版本升级时如果采用pg_upgrade或 dump/restore旧数据库中的 PostGIS 扩展记录仍然指向旧版本的 SQL 脚本。新部署的 PostGIS 3.5.0 的 control 文件里default_version是 3.5.0但数据库里记录的扩展版本可能是 3.4.x导致ALTER EXTENSION postgis UPDATE;时找不到对应的升级脚本。解决确认 bundle 的share/extension目录下包含了从旧版本到 3.5.0 的所有升级 SQL 脚本如postgis--3.4.0--3.5.0.sql。如果缺失需要从对应版本的 bundle 中补齐。然后执行ALTER EXTENSION postgis UPDATE TO 3.5.0; SELECT postgis_full_version();如果升级脚本缺失且无法补齐最后的办法是 dump 出空间数据在新库中重新CREATE EXTENSION postgis;再导入数据。这是血泪经验升级前务必备份并确认 bundle 包含完整的升级路径脚本。5. 让 PostGIS 3.5.0 在 PostgreSQL 17 上跑得更稳的几个进阶习惯5.1 用 postgis_full_version 做部署后的第一道体检每次部署完或升级后我第一件事就是跑SELECT postgis_full_version();。这条命令返回的字符串里包含了 PostGIS 版本、PostgreSQL 扩展接口版本、GEOS、PROJ、GDAL、LIBXML、LIBJSON 的版本信息。任何一个依赖缺失或版本异常这里都会体现出来。比如如果 PROJ 显示为空或版本号异常说明 proj 数据文件没部署好如果 GDAL 缺失postgis_raster相关功能会不可用。把这条命令的输出和官方发布说明里的依赖版本对照能提前发现大部分兼容性问题。5.2 空间索引的维护REINDEX 与 CLUSTER 的取舍空间索引用久了会膨胀尤其是频繁更新的表。GiST 索引不像 B-tree 那样有自动清理的成熟机制长时间运行后查询性能会下降。我的习惯是对更新频繁的空间表定期执行REINDEX INDEX CONCURRENTLY idx_name;重建索引。CONCURRENTLY选项在 PostgreSQL 17 上对 GiST 索引也支持不会阻塞读写。如果表的空间分布有聚集特征比如按区域查询为主可以考虑CLUSTER table_name USING idx_name;把数据按索引顺序物理重排但CLUSTER会锁表且后续插入的数据不会保持顺序适合读多写少的场景。5.3 坐标系选择的实际影响4326 还是 3857很多新手在建表时纠结用 4326WGS84 经纬度还是 3857Web Mercator。我的经验是存储用 4326计算距离时按需转换。4326 是原始 GPS 坐标没有投影变形适合存储和跨系统交换。3857 是投影坐标单位是米适合做距离和面积计算但在高纬度地区变形严重。如果业务以距离查询为主可以在 4326 存储的基础上对查询条件用::geography转换让 PostGIS 用球面模型计算精度足够且不需要额外维护投影列。如果性能要求极高且范围固定再考虑增加一个 3857 的生成列并建索引。5.4 离线环境的依赖完整性检查清单在没有网络的机器上部署最怕的是缺 DLL。我整理了一个检查清单部署后逐项确认检查项命令/方法预期结果扩展控制文件dir SHAREDIR\extension\postgis.control文件存在核心 DLLdir LIBDIR\postgis-3.dll文件存在几何引擎dir BINDIR\libgeos_c.dll文件存在坐标转换库dir BINDIR\libproj.dll文件存在PROJ 数据dir SHAREDIR\proj\proj.db文件存在扩展创建CREATE EXTENSION postgis;无报错版本查询SELECT postgis_full_version();返回完整版本串坐标转换SELECT ST_Transform(...);返回投影后坐标空间索引EXPLAIN ANALYZE SELECT ... WHERE ST_DWithin(...);显示 Index Scan这张表里的每一项都对应一个具体的失败模式部署后花五分钟过一遍比出了问题再回头翻日志要省事得多。5.5 一个我反复用的验证脚本最后分享一个我每次部署 PostGIS 后都会跑的验证脚本它把建表、插数据、空间查询、坐标转换、索引检查串在一起一次执行就能确认整条链路-- PostGIS 部署验证脚本 DO $$ BEGIN -- 1. 确认扩展已加载 IF NOT EXISTS (SELECT 1 FROM pg_extension WHERE extname postgis) THEN RAISE EXCEPTION PostGIS 扩展未创建; END IF; -- 2. 确认版本信息可读 PERFORM postgis_full_version(); -- 3. 确认坐标转换可用 PERFORM ST_Transform(ST_SetSRID(ST_MakePoint(0, 0), 4326), 3857); -- 4. 确认几何构造和距离计算可用 PERFORM ST_Distance( ST_SetSRID(ST_MakePoint(0, 0), 4326)::geography, ST_SetSRID(ST_MakePoint(1, 1), 4326)::geography ); RAISE NOTICE PostGIS 部署验证通过; END $$;这个脚本用DO块把关键检查串起来任何一步失败都会抛出异常并给出具体原因。我把它保存成一个.sql文件每次新环境部署后直接psql -f verify_postgis.sql跑一遍省去手动逐条测试的麻烦。部署这件事最怕的就是以为装好了、结果上线才发现某个函数不可用。提前花几分钟验证比事后救火划算得多。希望帮到你。本文还有配套的精品资源点击获取