PostGIS 3.3.6 源码编译实战：从依赖到空间查询验证

简介postgis-3.3.6.tar.gz 是 PostGIS 3.3.6 的源码安装包面向需要在 PostgreSQL 上构建空间数据库能力的开发者与 GIS 工程师。PostGIS 作为开源空间数据库扩展实现了 OpenGIS 规范可为对象关系型数据库补充点、线、多边形等空间数据类型以及空间索引、空间函数与操作符、空间关系分析、坐标参考系统转换和 WKT、WKB、GeoJSON、Shapefile 等格式的导入导出能力常用于城市规划、环境监测、交通物流与空间数据可视化等场景。压缩包约 16.98MB内含约 2000 个文件以 sql 脚本、po 与 pot 本地化文件、c 与 h 源码、wkt 测试数据、expected 回归预期结果、png 图示及 xml 配置为主另含 shp、dbf、shx 等示例数据结构完整便于编译安装与二次开发。目前已有 69 人学习下载适合希望深入理解空间数据库实现或自行部署 PostGIS 的读者参考。1. 从源码包到空间数据库postgis-3.3.6.tar.gz 到底解决什么问题拿到postgis-3.3.6.tar.gz这个包很多人第一反应是「解压、configure、make、install 四连」然后在CREATE EXTENSION postgis;那一步翻车。PostGIS 不是普通插件它是把 PostgreSQL 从「能存经纬度」升级成「能算空间关系」的空间数据库扩展3.3.6 属于 3.3 稳定分支的补丁版本主要修的是边界几何、栅格和拓扑相关的缺陷。它适合三类人做 GIS 后端、需要 ST_Distance/ST_Intersects 这类空间查询的开发者手里有 shp、GeoJSON、栅格影像要入库的分析人员以及被「装了 PostGIS 但函数报错」折磨过的运维。这篇笔记按源码编译这条最可控的路径走一遍把依赖、参数、验证和踩坑讲清楚让你在本地或测试环境真正跑通而不是停在make报错那一屏。2. 编译前必须锁死的依赖与版本组合源码编译 PostGIS 最怕的不是编译本身而是依赖版本对不上。3.3.x 对 GEOS、PROJ、GDAL 都有最低版本要求装低了 configure 直接拒绝装高了又可能因为 API 变动编译失败。所以第一步不是敲命令而是把版本组合定下来。2.1 三个核心依赖各自管什么GEOS 负责几何运算ST_Intersects、ST_Buffer、ST_Union 这些函数底层都调它PROJ 负责坐标转换ST_Transform 能不能把 4326 转到 3857 全靠它GDAL 负责栅格和格式读写做 raster 或 shp2pgsql 相关功能时必须有。三者缺一configure 阶段就会明确告诉你哪个没找到。常见做法是先确认 PostgreSQL 的服务端开发包pg_config在 PATH 里因为 PostGIS 编译时要靠它定位扩展目录。用下面命令确认# 确认 pg_config 可用且指向你要装扩展的那个 PostgreSQL which pg_config pg_config --version pg_config --pkglibdir # 扩展 .so 最终落地的目录 pg_config --sharedir # extension 控制文件落地目录逻辑说明pg_config必须来自目标 PostgreSQL 实例如果你机器上有多个版本装错目录会导致CREATE EXTENSION找不到文件。参数上重点看--pkglibdir和--sharedir后面排查「扩展不存在」时就是查这两个路径。2.2 依赖版本对照与安装下面这张表是我一般会先核对的最低组合具体以 configure 输出为准不要盲目追新依赖作用建议最低检查命令PostgreSQL宿主数据库11 及以上pg_config --versionGEOS几何运算3.8geos-config --versionPROJ坐标转换6.1proj或projinfoGDAL栅格/格式3.0gdal-config --versionJSON-CGeoJSON 支持0.13pkg-config --modversion json-c安装依赖时源码编译场景下要装的是-dev或-devel包只装运行库是不够的因为编译需要头文件。以常见发行版为例# Debian/Ubuntu 系装开发包而非仅运行库 sudo apt-get install -y build-essential postgresql-server-dev-all \ libgeos-dev libproj-dev libgdal-dev libjson-c-dev libxml2-dev # 装完立刻回读版本确认头文件和库一致 geos-config --version gdal-config --version逻辑说明build-essential提供 gcc/makepostgresql-server-dev-all提供 pg_config 和头文件。装完必须回读版本因为系统里可能同时存在多个 GEOSgeos-config指向的才是编译真正用的那个。如果geos-config版本低于 configure 要求要么升级要么用--with-geosconfig显式指定路径。提示依赖装完后先别急着解压 PostGIS把pg_config、geos-config、gdal-config三个命令的输出版本记下来后面 configure 报错时对照能省一半排查时间。3. 从 tar.gz 到 CREATE EXTENSION 的完整编译链路依赖齐了才进入正题。这一章按「解压 → configure → make → install → 建扩展 → 验证」走每一步都给出可抄的命令和失败时该看什么。3.1 解压与 configure 的关键参数# 解压源码包进入目录 tar -xzf postgis-3.3.6.tar.gz cd postgis-3.3.6 # 配置显式指定 pg_config开启常用组件 ./configure \ --with-pgconfig$(which pg_config) \ --with-geosconfig$(which geos-config) \ --with-gdalconfig$(which gdal-config) \ --with-projdir/usr \ --with-jsoncyes \ --with-raster \ --with-topology逻辑说明--with-pgconfig决定扩展装到哪个 PostgreSQL多实例机器上这是最关键的一个参数--with-raster和--with-topology分别开启栅格和拓扑功能不用可以不写但一旦后面要用 raster 又没编只能重来。configure 结束时会打印一张汇总表逐行看GEOS、PROJ、GDAL、Raster、Topology是不是yes任何一个是no都要回头补依赖别硬着头皮 make。参数上--with-projdir指向 PROJ 的安装前缀如果 PROJ 装在非标准路径比如自己编的这里要改成实际前缀否则坐标转换相关代码会链接失败。3.2 make 与 make install 的取舍# 并行编译-j 后面跟 CPU 核数别开太大以免内存爆 make -j4 # 安装到 pg_config 指定的目录通常需要写权限 sudo make install # 如果还要装配套的命令行工具shp2pgsql 等再执行 sudo make install逻辑说明make -j4用 4 个并行任务加速内存小的机器建议降到-j2否则 gcc 被 OOM kill 会报莫名其妙的错。make install把.so、.control、.sql文件分别拷到pkglibdir和sharedir这一步不需要重启数据库但需要数据库有权限读取这些文件。编译报错时优先看第一个 error不要看最后一行。常见的是头文件找不到依赖没装 dev 包和符号未定义库版本不匹配。把 configure 汇总表再对一遍基本能定位。3.3 建扩展与最小验证-- 连到目标库创建扩展 CREATE EXTENSION postgis; -- 验证版本和核心能力 SELECT postgis_full_version(); SELECT ST_Distance( ST_GeomFromText(POINT(0 0), 4326), ST_GeomFromText(POINT(1 1), 4326) );逻辑说明CREATE EXTENSION postgis会执行扩展的 SQL 脚本把函数、类型、操作符注册进当前库。postgis_full_version()返回的字符串里包含 PostGIS、GEOS、PROJ、GDAL 的版本一眼就能看出编译时链接的是不是你以为的那套库。第二个查询验证几何运算链路是否通返回的是度数距离因为 4326 是地理坐标如果报函数不存在说明扩展没建成功或建到了别的库。注意CREATE EXTENSION是按库生效的同一个 PostgreSQL 实例里每个要用空间功能的库都要单独执行一次别以为装一次就全局可用。4. 避坑与排查编译和建扩展阶段最常见的 5 个翻车点这一章全是血泪经验每条按「现象 → 原因 → 解决」写遇到时直接对号入座。4.1 CREATE EXTENSION 报 could not open extension control file现象执行CREATE EXTENSION postgis;提示找不到控制文件。原因是make install装到了另一个 PostgreSQL 的目录或者当前库连的实例和 pg_config 指向的不是同一个。解决用pg_config --sharedir确认控制文件应落地的路径去该路径下看有没有extension/postgis.control没有就说明装错实例重新用正确的 pg_config 编译安装。4.2 编译时报 geos_c.h 找不到现象make 阶段报fatal error: geos_c.h: No such file or directory。原因是只装了 GEOS 运行库没装开发包。解决安装libgeos-dev或对应发行版的 devel 包装完用geos-config --cflags确认头文件路径再重新 configure。4.3 ST_Transform 报找不到 proj 数据库现象建扩展成功但一调用ST_Transform就报坐标转换失败或找不到 proj.db。原因是 PROJ 6 以后坐标数据独立成 proj.db 文件编译时链接的 PROJ 和运行时找不到的数据目录不一致。解决确认projinfo能正常输出设置PROJ_LIB环境变量指向 proj.db 所在目录或在 configure 时用--with-projdir指到正确前缀。4.4 make 中途被 killed现象编译到某个大文件时进程被系统杀掉没有明确报错。原因是并行编译占用内存过高触发 OOM。解决降低并行度用make -j1或make -j2重来同时关掉其他吃内存的进程。这类问题在小内存云主机上特别常见。4.5 升级后旧库函数报错现象从旧版本 PostGIS 升级到 3.3.6 后原有查询报函数签名不匹配。原因是扩展升级需要执行ALTER EXTENSION postgis UPDATE;而不是重新CREATE EXTENSION。解决先备份再在目标库执行ALTER EXTENSION postgis UPDATE TO 3.3.6;然后用postgis_full_version()确认版本最后跑一遍业务查询验证。5. 让 3.3.6 真正好用的三个进阶习惯编译通过只是起点能不能长期稳定用取决于几个习惯。第一个是版本锁定把 PostgreSQL、GEOS、PROJ、GDAL、PostGIS 的版本组合记进部署文档下次换机器照抄别让「上次能编这次不行」反复发生。第二个是验证脚本化把postgis_full_version()、几个核心空间函数的调用写成一个verify.sql每次部署后跑一遍比人肉点查询可靠。-- verify.sql部署后一键验证核心能力 SELECT postgis_full_version(); SELECT ST_AsText(ST_Transform(ST_GeomFromText(POINT(116 40), 4326), 3857)); SELECT ST_Area(ST_GeomFromText(POLYGON((0 0,1 0,1 1,0 1,0 0)), 4326));逻辑说明第一行确认版本组合第二行验证坐标转换链路第三行验证几何计算。三行都过说明编译、链接、数据目录、扩展注册四条链路都通。参数上注意 4326 转 3857 是 Web 墨卡托做地图切片时最常用如果这行报错优先查 PROJ 数据目录。第三个习惯是给扩展单独建库做实验。生产库只装稳定版本新版本先在实验库CREATE EXTENSION验证确认业务查询没问题再升级。我自己就吃过直接在业务库ALTER EXTENSION的亏升级脚本跑到一半卡住回滚又因为拓扑数据不一致折腾了半天。后来固定成「实验库先跑、验证脚本先过、再动生产」的流程再没出过这类事。源码编译这条路看着麻烦但每一步都可控比依赖不明来源的二进制包踏实得多。希望帮到你。本文还有配套的精品资源点击获取