pg_config是PostgreSQL安装包自带的一个命令行工具，通常位于安装目录的bin子目录下。它不依赖数据库服务运行，只要安装了PostgreSQL的服务器端或开发包，就能直接执行。执行不带任何参数的命令可以获得所有编译配置项，包括版本号、编译时使用的GCC版本、configure参数、头文件路径、库文件路径等。这些信息对于排查扩展编译问题、构建自动化脚本以及确认环境差异都非常关键。
如果想要查看某个具体配置项，可以在命令后面加上选项。例如pg_config --includedir会输出头文件目录，pg_config --libdir会输出库文件目录。这种按需查询方式适合在脚本中拼接路径，也便于阅读。对于不熟悉PostgreSQL目录结构的用户来说，先完整执行一遍pg_config，再根据输出逐项确认路径，是建立环境认知的最快方式。
不同安装方式产生的输出会有明显差异。源码编译安装时，路径通常跟--prefix参数一致；使用apt或者yum安装时，路径会分散到/usr/include/postgresql和/usr/lib/postgresql等位置。因此不能只凭经验猜测，而应以pg_config的实际输出为准。特别是在同时存在多个PostgreSQL版本的服务器上，路径差异会直接影响扩展安装位置和运行时加载。
一、pg_config的基础用法与输出概览
直接执行pg_config命令，会得到类似下面的输出。输出项前面是变量名，等号后面是对应的值。比如VERSION表示完整版本号，PG_VERSION表示主版本号，BINDIR表示可执行文件目录，DOCDIR表示文档目录。这些变量名在后续的构建脚本中可以直接引用。
$ pg_config BINDIR = /usr/lib/postgresql/14/bin DOCDIR = /usr/share/doc/postgresql-doc-14 HTMLDIR = /usr/share/doc/postgresql-doc-14 INCLUDEDIR = /usr/include/postgresql PKGINCLUDEDIR = /usr/include/postgresql INCLUDEDIR-SERVER = /usr/include/postgresql/14/server LIBDIR = /usr/lib/x86_64-linux-gnu PKGLIBDIR = /usr/lib/postgresql/14/lib LOCALEDIR = /usr/share/locale MANDIR = /usr/share/man SHAREDIR = /usr/share/postgresql/14 SYSCONFDIR = /etc/postgresql-common PGXS = /usr/lib/postgresql/14/lib/pgxs/src/makefiles/pgxs.mk CONFIGURE = '--build=x86_64-linux-gnu' '--prefix=/usr' '--includedir=/usr/include' '--mandir=/usr/share/man' '--infodir=/usr/share/info' '--sysconfdir=/etc' '--localstatedir=/var' '--libexecdir=/usr/lib/postgresql' '--disable-maintainer-mode' '--with-icu' '--with-openssl' '--with-libxml' '--with-libxslt' '--with-tcl' '--with-perl' '--with-python' '--with-pam' '--with-ldap' '--with-gssapi' '--with-systemd' '--with-selinux' '--with-uuid=e2fs' '--with-lz4' '--with-zstd' CC = gcc CPPFLAGS = -Wdate-time -D_FORTIFY_SOURCE=2 CFLAGS = -g -O2 -ffile-prefix-map=/build/postgresql-14/. -fstack-protector-strong -Wformat -Werror=format-security -fno-omit-frame-pointer LDFLAGS = -Wl,-z,relro -Wl,-z,now LIBS = -lpgcommon -lpgport -lpq -lpthread -lssl -lcrypto -lz -lreadline -lrt -lcrypt -ldl -lm VERSION = PostgreSQL 14.10 (Ubuntu 14.10-0ubuntu0.22.04.1)
从输出中可以看到，这个实例是通过Ubuntu软件包安装的PostgreSQL 14，启用了ICU、OpenSSL、libxml、libxslt、Perl、Python、PAM、LDAP、GSSAPI、LZ4、ZSTD等扩展功能。CFLAGS中包含-O2和-g，说明带有优化和调试信息。CONFIGURE中的--with参数则直接反映了编译时的功能开关。这些信息对于判断某个扩展能否正常编译非常重要。
pg_config支持单独查询某个变量，例如pg_config --version只输出版本号，pg_config --pgxs只输出PGXS构建文件路径。这种细粒度查询可以嵌入到Makefile或shell脚本中，避免解析完整输出的麻烦。部分选项在旧版本中可能不存在，比如--includedir-server，此时可以使用--pkgincludedir替代，具体可用pg_config --help查看当前版本支持的选项列表。
二、重点输出项与编译配置解读
版本信息包括VERSION和PG_VERSION。VERSION是完整版本号，包含编译平台信息；PG_VERSION是主版本号，比如14、15。主版本号决定了扩展的ABI兼容性，一个为PostgreSQL 14编译的扩展通常不能直接加载到PostgreSQL 15中，需要重新编译。因此扩展构建时最好从pg_config动态获取PG_VERSION，而不是硬编码。
路径信息包含多个变量，最常用的是INCLUDEDIR、PKGINCLUDEDIR、INCLUDEDIR-SERVER、LIBDIR和PKGLIBDIR。其中INCLUDEDIR-SERVER指向服务器端开发所需的头文件目录，里面包含postgres.h、fmgr.h、access/htup.h等核心头文件。PKGLIBDIR通常存放扩展的动态库文件，扩展安装时会把.so文件复制到这个目录。理解这些路径，可以避免在Makefile中写死类似/usr/include/postgresql/14/server这样的绝对路径。
CONFIGURE和CFLAGS是两个容易混淆的输出项。CONFIGURE记录的是安装PostgreSQL时传给configure脚本的参数，反映的是功能选择；CFLAGS则是C编译器在编译阶段使用的选项，反映的是优化级别、调试信息和安全加固等。比如CFLAGS中出现-O2表示进行了常规优化，出现-g表示保留了调试符号，出现-fstack-protector-strong表示启用了栈保护。这些参数在重新编译相同配置的PostgreSQL或排查ABI问题时具有参考价值。
特性开关通常隐藏在CONFIGURE参数中。例如--with-openssl表示支持SSL连接，--with-icu表示使用ICU库处理排序规则，--with-lz4和--with-zstd表示支持对应的压缩算法。如果扩展代码依赖OpenSSL，而当前PostgreSQL没有编译该选项，链接时就会报undefined reference错误。通过pg_config --configure提前确认这些开关，能在编译前就发现环境是否满足要求。
三、在扩展开发与构建脚本中的实际应用
PostgreSQL扩展通常使用PGXS构建体系，它的Makefile会调用pg_config获取必要变量。一个最小扩展的Makefile可以这样写：先定义扩展名和数据文件，再指定PG_CONFIG变量，最后通过shell调用pg_config得到PGXS路径并包含它。PGXS会自动处理头文件目录、库目录、编译参数以及安装路径。
EXTENSION = my_ext DATA = my_ext--1.0.sql MODULE_big = my_ext OBJS = my_ext.o PG_CONFIG = pg_config PGXS := $(shell $(PG_CONFIG) --pgxs) include $(PGXS)
在自动化编译脚本中，也可以直接使用pg_config的输出拼接路径。例如通过pg_config --includedir-server获取服务器头文件目录，再传给gcc的-I参数。如果脚本需要兼容不同PostgreSQL版本，可以先判断选项是否可用，不可用则回退到pg_config --pkgincludedir。这样脚本在不同发行版上都能正确找到头文件，不会因为路径差异而失败。
链接阶段同样需要pg_config提供的路径。如果编写独立工具，要使用pg_config --libdir获取库目录，再通过-L参数传递给链接器。注意libpq和postgres库的链接方式因版本不同可能有差异，直接使用pg_config --libs可以返回推荐的链接参数，避免手动拼接出错。对于扩展开发，PGXS已经处理了大部分链接逻辑，通常不需要手动指定。
除了路径和编译参数，pg_config还可以帮助判断是否安装了服务器端开发包。很多系统默认只安装客户端包，此时pg_config可能不存在，或者存在但缺少INCLUDEDIR-SERVER对应的目录。通过在脚本开头检查pg_config --includedir-server是否返回有效目录，可以提前给出友好提示，引导用户安装postgresql-server-dev或postgresql-devel之类的开发包。
四、常见误区与问题排查
一个常见误区是只安装客户端包就尝试编译扩展。客户端包通常不包含服务器端头文件，pg_config命令也可能不存在。此时需要安装对应版本的开发包。不同发行版包名不同，Debian/Ubuntu下是postgresql-server-dev-版本号，RHEL/CentOS下是postgresql-devel。确认是否安装开发包，可以先执行which pg_config，再看pg_config --includedir-server指向的目录是否存在且包含postgres.h。
另一个问题是多个PostgreSQL版本共存时，命令可能指向错误版本。建议使用绝对路径调用对应版本的pg_config，或者在PATH中调整顺序。例如源码安装了PostgreSQL 14和系统自带PostgreSQL 12时，直接执行pg_config可能输出12的配置，导致扩展安装到错误目录。解决方法是使用完整路径，比如/usr/pgsql-14/bin/pg_config。在Makefile中也可以把PG_CONFIG变量显式设置为这个路径，避免被环境变量干扰。
还有部分用户会混淆CONFIGURE和CFLAGS的作用。CONFIGURE是configure脚本参数，表示编译前的功能选择；CFLAGS是C编译器选项，表示具体编译阶段的优化和警告级别。如果需要重新编译相同选项的PostgreSQL，可以保存pg_config --configure的输出作为参照，但要注意该输出不包含环境变量中的CFLAGS和LDFLAGS，重新构建时还要结合当时的编译脚本。另一个细节是CONFIGURE输出中的单引号仅是展示格式，不代表真实参数包含引号。
如果扩展编译时提示找不到postgres.h，先检查-I参数是否来自pg_config的PKGINCLUDEDIR或INCLUDEDIR-SERVER，而不是手动猜测/usr/include/postgresql。不同安装方式这个目录差别很大，用pg_config输出最可靠。链接时若出现undefined reference错误，则要确认当前PostgreSQL是否编译了扩展依赖的库，比如OpenSSL、ICU或XML。通过pg_config --configure查看功能开关，往往能快速定位是缺库还是版本不匹配。
pg_configPostgreSQL编译配置编译选项修改时间：2026-09-28 03:17:38