Debian Golang打包有哪些常见误区

Debian Golang 打包的常见误区与规避

一 构建环境与工具链

• 直接在干净的 chroot/CI 里运行 debuild 报 “go: Command not found”，常因未安装 golang-go 或构建环境 PATH 受限；应优先通过 apt 安装 golang-go 并验证 go version，同时确保 debian/rules 中的 make/go 调用能在受限环境找到 go 命令。
• 误以为任意 Go 版本都能稳定打包；实际上应与目标发行版的 golang-go 版本匹配，避免 API/构建差异导致 reproducibility 与 FTBFS。
• 未使用 dh-golang 管理模块依赖与构建流程；手工脚本容易遗漏 vendor/模块下载、架构参数等，推荐采用 dh-golang 或 dh-make-golang 生成骨架并遵循 Debian Go 团队的工作流。

二 链接方式与可移植性

• 在 CGO_ENABLED=1 下构建，二进制会依赖 glibc/C 库；把这样的二进制放进极简镜像（如 alpine）常出现 “Error loading shared library libresolv.so.2” 等缺库错误。若程序不依赖 C 库，应设 CGO_ENABLED=0 进行纯静态构建以提升可移植性。
• 将 Alpine 基础镜像与 glibc 发行版的二进制混用，易触发动态链接不兼容；要么在 Debian 系列基础镜像中运行静态二进制，要么在 Alpine 中用 CGO_ENABLED=0 重构建。
• 滥用 external linking 与 “-ldflags ‘-linkmode external’ -extldflags ‘-static’” 追求“更静态”，在开启 CGO 时往往适得其反，增加构建复杂度与不确定性；优先选择纯 Go 依赖或明确需要 CGO 的场景再配置。

三 依赖处理与打包边界

• 把 整个模块缓存（~/go/pkg/mod） 或大量源码打进 .deb，导致包体膨胀与不必要的文件归属问题；应仅安装编译产物与必要资源，依赖通过 dh-golang 从 Debian 仓库解析并打包。
• 将“上游发布”和“Debian 集成”混为一谈；常规做法是先按 Go 社区方式开发与版本管理，再用 dh-golang 创建 Debian 包，必要时先补齐缺失的 Go 库依赖包。
• 用 dh-make-golang 生成骨架后不检查依赖清单与上游 go.mod，遗漏间接依赖或版本约束，导致构建时解析失败；应核对依赖、必要时调整 import path 映射与打包顺序。

四 Lintian 与交付流程

• 遇到 lintian 警告就“无脑绕过”或关闭检查；更可取的是使用 lintian override 精准忽略已评估过的告警，或在必要时用 dpkg-buildpackage -us -uc -b 仅构建二进制包（不运行 lintian），但需记录原因并保证质量。
• 交付前不在目标 Debian/Ubuntu 环境安装测试，遗漏 /usr/bin 安装路径、权限、服务文件、systemd 单元、man 手册等细节；应在目标环境完成安装、启动与功能回归测试。

五 实用检查清单

• 构建环境：已安装 golang-go，debuild 能找到 go；版本与目标发行版匹配。
• 链接策略：默认 CGO_ENABLED=0 纯静态；确需 CGO 时明确依赖并做好可移植性验证。
• 依赖管理：使用 dh-golang 拉取与解析模块依赖，不把 mod cache 打进包。
• 产物精简：仅含可执行文件与必要资源，控制包体大小与文件归属。
• 质量保障：通过 lintian（或合理 override），在目标环境完成安装与运行测试。