PostgreSQL的扩展机制让数据库可以按需加载新功能，PostGIS、pg_stat_statements这些常用组件本质上都是扩展。不过自己动手写一个扩展时，很多人卡在了打包和安装环节：编译明明成功了，执行CREATE EXTENSION却提示找不到文件；或者换了一台机器就装不上。这篇文章把扩展的组成结构、打包规范和安装流程完整梳理一遍，帮你避开这些常见的坑。
一、PostgreSQL扩展由哪些文件组成
一个标准的PostgreSQL扩展通常包含四类文件。第一类是控制文件，扩展名固定为.control，文件名必须与扩展名一致，比如myext.control对应扩展名myext。控制文件描述了扩展的基本元信息，包括版本、依赖、是否可重定位等，安装后会被放到share/extension目录下。
第二类是SQL脚本文件，命名格式一般是扩展名--版本.sql，例如myext--1.0.sql。这个文件里放着扩展对象的定义语句，安装时数据库会解析它并把函数、视图、表结构等内容记录到系统目录中。第三类是共享库文件，也就是编译C代码得到的.so文件（Windows上是.dll），如果扩展包含C语言函数，这个文件会被放到lib目录，PostgreSQL在首次调用函数时动态加载它。
第四类是可选的注释文件和数据文件，比如extension--1.0--1.1.sql这类升级脚本，以及文档、测试用例等。理解这个结构很关键，因为打包的本质就是把这些文件准确地放到PostgreSQL期望的目录里，目录对了，CREATE EXTENSION才能正常工作。
二、使用PGXS编写Makefile进行打包
PostgreSQL官方提供了PGXS（PostgreSQL Extension Infrastructure）构建体系，开发者不需要手写复杂的编译规则，只要一个简单的Makefile就能完成编译和安装。PGXS会自动从当前环境的PostgreSQL安装中读取编译参数，保证编译出的二进制文件与当前数据库版本兼容。
下面是一个典型扩展的Makefile示例：
# 扩展名，必须与control文件名一致 EXTENSION = myext # 需要安装的SQL脚本和control文件 DATA = myext--1.0.sql DATA_broken = # C源文件，编译成共享库 MODULES = myext # 使用PGXS构建体系，这是固定写法 PG_CONFIG = pg_config PGXS := $(shell $(PG_CONFIG) --pgxs) include $(PGXS)
写好Makefile后，在扩展源码目录依次执行三个命令：make完成编译，make install把文件复制到PostgreSQL的安装目录，make installcheck可以运行回归测试验证安装是否正确。这里有个容易踩坑的地方：如果机器上装了多个版本的PostgreSQL，make时用的是哪个pg_config，文件就装到哪个版本的目录里。可以用pg_config --pkglibdir和pg_config --sharedir确认目标路径，避免装错位置。
控制文件的编写也有讲究。下面是一个完整示例：
# myext.control comment = '一个演示用的扩展' default_version = '1.0' module_pathname = '$libdir/myext' relocatable = false schema = public requires = 'plpgsql'
其中relocatable决定扩展对象是否可以移动到其他模式，涉及表存储的扩展一般设为false；requires声明依赖的其他扩展，安装时会先自动装依赖项。这些字段直接影响CREATE EXTENSION的行为，打包时要仔细核对。
三、三种常见安装方式的对比与选择
第一种是源码编译安装，适合自研扩展或者需要定制编译选项的场景。流程是拿到源码后执行make && make install，前提是机器上装有PostgreSQL的开发头文件。Debian系需要安装postgresql-server-dev包，RedHat系则是postgresql-devel，缺了头文件编译会直接报错。
第二种是通过PGXN（PostgreSQL Extension Network）安装。PGXN是官方的扩展分发网络，装好pgxn客户端后一条命令就能完成下载编译安装：
# 安装pgxn客户端 pip install pgxnclient # 从PGXN搜索并安装扩展 pgxn search postgis pgxn install postgis
第三种是使用操作系统的包管理器，比如apt install postgresql-contrib或yum install postgresql14-contrib。这种方式最省事，扩展文件会被放到包管理器管理的目录，但要注意它安装的目录可能与源码编译的pg_config指向的目录不同，混用两种安装方式时容易出现文件分散在两处的问题。
四、安装后的验证与常见故障排查
文件就位后，连接数据库执行CREATE EXTENSION myext;即完成安装。验证是否成功可以查询pg_extension系统视图：
-- 查看已安装的扩展及版本 SELECT extname, extversion FROM pg_extension; -- 查看数据库中有哪些扩展可供安装 SELECT name, default_version FROM pg_available_extensions WHERE name = 'myext';
如果pg_available_extensions里查不到扩展，说明control文件没放到share/extension目录，检查安装路径即可。如果创建时报错找不到函数实现，多半是.so文件不在lib目录，或者编译时的PostgreSQL版本与运行版本不一致导致符号不兼容。还有一种情况是版本升级时报错，这时需要补充形如myext--1.0--1.1.sql的升级脚本，再用ALTER EXTENSION myext UPDATE TO '1.1';完成版本迁移。
掌握这套打包与安装流程后，无论是发布自己的扩展还是部署第三方扩展，都能做到心里有数。核心记住一点：扩展安装就是把几类文件放到正确目录的过程，遇到问题时从文件和目录入手排查，绝大多数故障都能快速定位。
PostgreSQL扩展PGXNCREATE EXTENSION修改时间：2026-09-12 16:34:32