Debian Golang 打包常见问题与解决方法
一 环境准备与构建工具链
- 问题：构建时报错 “go: Command not found”。原因多为构建环境未安装 golang-go 或 PATH 未包含 Go 工具链。解决：在构建环境中安装 Go（如 sudo apt-get install golang-go），并确保 go version 可用；如使用 dh-golang，在 debian/control 的 Build-Depends 中加入 dh-golang 与 golang-go/golang-any，在 debian/rules 使用 %:: dh $@ --with golang。示例：
- debian/control 片段：Build-Depends: debhelper (>= 10), dh-golang, golang-go
- debian/rules：%:: dh $@ --with golang
- 问题：依赖下载慢或失败。解决：设置 Go 代理（如 GOPROXY=https://goproxy.cn,direct），提升模块解析稳定性与速度。
二 静态链接与 Cgo 相关错误
- 问题：启用 Cgo 后二进制依赖外部 C 库，迁移到 Alpine 等精简镜像时报错（如找不到 libresolv.so.2）。解决：若业务允许，关闭 Cgo 进行纯静态构建（CGO_ENABLED=0），生成不依赖外部 C 库的二进制；示例：CGO_ENABLED=0 go build -o server main.go。
- 问题：需要 Cgo 的动态链接但目标镜像缺少库。解决：改用 debian:buster-slim 等包含常用 C 库的镜像，或在镜像中安装所需运行时库，避免跨发行版/精简镜像的库缺失问题。
三 使用 dh-golang 的正确姿势
- 问题：手工编写 debian/rules 复杂、易错。解决：采用 dh-golang 简化流程，自动处理 Go 模块依赖、构建与安装；典型 debian/rules 仅需 %:: dh $@ --with golang。
- 问题：模块缓存与构建产物污染。解决：在 rules 中设置临时工作区与二进制目录（如 export GOPATH=$(CURDIR)/.gopath; export GOBIN=$(CURDIR)/bin），并在 override_dh_auto_clean 中清理，确保可重复构建与干净产物。
四 Lintian 警告与二进制包构建
- 问题：静态链接的单文件二进制触发 lintian 不适用的警告（如 hardening 相关、缺少手册页）。解决：优先通过构建流程与系统加固选项满足规范；确需忽略时，使用 lintian overrides（例如在 debian/lintian-overrides/ 中写入“binary-without-manpage”“hardening-no-relro”等条目），避免过度滥用。
- 问题：希望快速产出 .deb 二进制包用于测试或内部分发。解决：在不追求完整规范检查的场景，可直接用 dpkg-buildpackage -us -uc -b 构建二进制包；注意这不会运行 lintian，适合临时验证与内部交付。
五 实用最小示例
- 目录结构：my-go-app/ 下包含源码与 debian/ 目录。
- debian/control 片段：
- Source: my-go-app
- Section: utils
- Priority: optional
- Maintainer: Your Name you@example.com
- Build-Depends: debhelper (>= 10), dh-golang, golang-go
- Standards-Version: 4.5.0
- Package: my-go-app
- Architecture: any
- Depends: ${shlibs:Depends}, ${misc:Depends}
- Description: Short desc.
- debian/rules：
- #!/usr/bin/make -f
- export GOPATH := $(CURDIR)/.gopath
- export GOBIN := $(CURDIR)/bin
- %:: dh $@ --with golang
- override_dh_auto_clean:
- dh_auto_clean
- rm -rf $(GOPATH) $(GOBIN)
- 构建与检查：
- debuild -us -uc
- 如需忽略特定 lintian 警告：在 debian/lintian-overrides/my-go-app 添加条目。
