Go静态链接GraphicsMagick(gmagick)编译报未定义引用如何解决

你遇到的链接报错来自两个核心问题：

• 初始编译命令存在根本性错误：设置CGO_ENABLED=0会直接禁用CGO特性，而go-gmagick是基于CGO封装调用C语言实现的GraphicsMagick库，禁用CGO后完全无法完成C代码的链接流程。
• 静态链接时没有把GraphicsMagick依赖的所有传递性依赖库加入链接参数，才会出现大量undefined reference报错，从报错符号可以对应到缺失的依赖：
  • exp/sin/sqrt/fmod等数学函数符号：来自C标准数学库libm
  • GOMP_*/omp_*开头的并行相关符号：来自GCC的OpenMP运行时库libgomp
  • XOpenDisplay/XSetErrorHandler等X11相关符号：来自X11客户端库libX11，是系统源里的GraphicsMagick默认开启的图片显示、动画预览功能引入的依赖，绝大多数服务端部署场景完全用不到这部分功能。

方案一：编译裁剪版GraphicsMagick静态库（推荐） #

这个方案产出的二进制最干净，没有无用依赖，体积更小，是生产环境静态编译的首选方案：

• 先卸载系统自带的libgraphicsmagick1-dev包，避免和自行编译的版本冲突。
• 下载GraphicsMagick源码，编译静态库版本时关闭不需要的功能，参考编译配置：

./configure --disable-shared --enable-static --disable-openmp --without-x
# 其余可选依赖（比如jpeg、png、webp等格式支持）按实际业务需要开启，不需要的功能全部用--without-xxx参数关闭即可
make -j$(nproc)
make install

上述参数里--without-x会直接移除X11相关依赖，--disable-openmp会移除OpenMP并行相关依赖，从根源上解决这两类符号缺失问题。

• 编译安装完成后，确认静态库所在路径（默认安装在/usr/local/lib）在系统链接搜索路径内，使用如下正确命令编译Go程序：

CGO_ENABLED=1 go build -ldflags='-extldflags "-static -lm"' 项目入口文件.go

• 编译完成后执行ldd 产出的二进制文件名，如果输出not a dynamic executable就说明静态编译成功，二进制可以直接拷贝到同架构的目标环境运行，不需要额外装依赖。

方案二：直接使用系统自带静态库，补全所有链接依赖 #

如果不想重新编译GraphicsMagick，可以手动补全所有传递依赖完成静态链接，注意静态链接时库的顺序要求是：依赖其他库的文件放在前面，被依赖的库放在后面。

• 先安装所有依赖的静态库版本：

apt install -y libgomp1 libx11-dev libsm-dev libice-dev libxext-dev
# 安装时注意确认包内包含对应.a静态文件，不要只装动态库版本

• 使用如下命令编译，把所有需要链接的库全部写入链接参数：

CGO_ENABLED=1 go build -ldflags='-extldflags "-static -lGraphicsMagick -lgomp -lX11 -lSM -lICE -lXext -lm"' 项目入口文件.go

这个方案的缺点是会把完全用不到的X11相关代码也打包进二进制，产物体积会大很多，而且X11相关依赖经常还会引入更多传递依赖，如果编译时还有新的undefined reference报错，对应查清楚符号所属的库，追加到链接参数末尾即可。

• 遇到未定义符号报错时，可以用nm -g 静态库路径 | grep 待查符号名命令，确认符号所属的静态库，再把对应库加入链接参数。
• 只要项目用到任何CGO绑定的C库，就不能设置CGO_ENABLED=0，否则必然链接失败。
• 静态链接和动态链接的逻辑不同，C链接器不会自动拉取所有传递依赖，所有间接依赖的库都需要手动写到链接参数里。

内容的提问来源于stack exchange，提问作者Oscar Zarrus