Docker多阶段构建Go程序出现未定义错误，求解决方案

问题背景 #

学习Go语言时编写了一个依赖govips/v2的PDF转图片程序，本地构建正常，但Docker构建时持续提示govips相关符号未定义，核心报错示例：

#18 4.394 ./pdf2png.go:29:29: undefined: vips.ImageType
#18 4.394 ./pdf2png.go:30:7: undefined: vips.ImageTypeJPEG
#18 4.394 ./pdf2png.go:41:25: undefined: vips.ImageRef
#18 4.394 ./pdf2png.go:41:86: undefined: vips.ImageMetadata

项目结构：

.
├── README.md
├── convert.go
├── dockerfile
├── go.mod
├── go.sum
├── main.go
├── pageindices.go
├── pageindices_test.go
├── pdf2png.go
└── pdf2png_test.go

go.mod核心内容：

module github.com/felixgao/pdf_to_png

go 1.20

require github.com/davidbyttow/govips/v2 v2.13.0

问题根源 #

1. CGO禁用导致绑定失效：govips是基于CGO绑定libvips的库，Docker构建时设置了CGO_ENABLED=0，直接禁用CGO功能，Go编译器无法处理govips中的C语言绑定代码，因此出现符号未定义错误。本地构建默认CGO_ENABLED=1且已安装libvips依赖，所以构建正常。
2. 模块路径不匹配：Docker中工作目录设为/go/src/github.com/felixgao/pdf2img，但go.mod声明的模块是github.com/felixgao/pdf_to_png，路径不一致可能导致模块导入解析异常。
3. LD_LIBRARY_PATH未生效：手动编译的libvips位于/usr/local/lib，但构建阶段的路径设置未在build命令中生效，编译器无法找到libvips库文件。

修复步骤 #

1. 开启CGO并调整构建命令 #

修改Dockerfile构建阶段的go build命令，启用CGO并确保编译器能找到libvips库：

# Build the Go app with ldflags
RUN export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib && \
    CGO_ENABLED=1 GOOS=linux go build -a \
    -ldflags="-s -w -h -X main.Version=${PDF2IMG_VERSION}" \
    -o pdf2png

2. 统一模块路径 #

将Docker工作目录修改为与go.mod一致的路径：

# create a working directory inside the image
WORKDIR /go/src/github.com/felixgao/pdf_to_png

3. 确保运行阶段加载libvips库 #

在prod阶段添加环境变量指定libvips库路径：

FROM golang:${GOLANG_IMAGE_TAG} as prod
WORKDIR /app/
RUN apk --update add --no-cache \
    fftw glib expat libjpeg-turbo libpng \
    libwebp giflib librsvg libgsf libexif lcms2
WORKDIR /root/
# 设置库路径环境变量
ENV LD_LIBRARY_PATH=/usr/local/lib
COPY --from=base /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=base /usr/local/lib/* /usr/local/lib/
COPY --from=base /go/src/github.com/felixgao/pdf_to_png/pdf2png .

4. 验证构建 #

执行Docker构建命令测试：

docker build -t pdf2png .

额外说明 #

• 禁用CGO仅适用于纯Go项目，依赖CGO的库必须开启CGO才能正常构建。
• Alpine环境下编译libvips时，已通过configure参数禁用不必要功能，确保库体积符合容器化需求。

内容的提问来源于stack exchange，提问作者Felix Gao