简体中文
macOS 下为 Go 服务打包 RPM 快速入门指南

本文定位:快速入门
这是一篇快速入门文章,目标只有一个:让你在最短时间内,在 macOS 上把一个 Go 服务成功打成可安装的 RPM 包并跑通验证。因此文中只讲主链路,不涉及多包管理、依赖声明、签名、多架构并行构建、CI/CD 集成等进阶内容。
如果你已经跑通过一次,想要看更贴近生产的做法(真实项目中的目录约定、脚本化构建、版本号与制品管理、灰度发布配合等),我会另外整理一篇基于实际项目的应用干货,届时在文末更新链接。
在 macOS 上开发 Go 服务、最终部署到 Linux 服务器时,经常需要打成 RPM 包。本文主推 nFPM 方案——纯 Go 编写、零 rpmbuild 依赖、安装快、配置简单;同时记录一次在 macOS 13 上用 brew install rpm 配合 FPM 的真实踩坑:源码编译一个半小时仍未完成。最后给出 Docker 备选方案。
方案选型:为什么主推 nFPM
| 方案 | 依赖 | macOS 13 体验 | 推荐度 |
|---|---|---|---|
| nFPM | 纯 Go 二进制,无 rpmbuild | 安装快,无源码编译 | ⭐⭐⭐⭐⭐ 首选 |
| FPM + brew rpm | Ruby + rpmbuild 工具链 | 触发大量源码编译,耗时不可控 | ⭐⭐ 备选 |
| Docker + FPM | Docker Desktop | 环境纯净,首次拉镜像较慢 | ⭐⭐⭐⭐ 备选 |
nFPM 是 GoReleaser 团队维护的纯 Go 打包器,直接写出 RPM 格式,完全不调用 rpmbuild,因此不会拉起 openssl、rust、llvm 那一整套 Linux 工具链。这是它在你机器上最核心的优势。
第一步:交叉编译 Go 服务为 Linux 二进制
nFPM 不负责编译,需要先手动交叉编译。纯 Go 项目(不依赖 CGO)命令很简单:
bash
# 编译为 Linux amd64 架构的静态二进制
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o my-service ./cmd/server
chmod +x my-service注意:保持
CGO_ENABLED=0编译出的静态二进制可在任意 Linux 发行版运行,不会遇到 glibc 版本问题。若项目依赖 CGO(如 sqlite3),交叉编译会复杂得多,需要额外工具链。
第二步:准备 systemd 服务文件
如果希望 RPM 安装后能通过 systemctl 管理服务,准备一个 .service 文件:
ini
# my-service.service
[Unit]
Description=My Go Service
After=network.target
[Service]
Type=simple
User=my-service
WorkingDirectory=/usr/local/bin
ExecStart=/usr/local/bin/my-service
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target第三步:安装 nFPM
推荐用 GoReleaser 的 tap 安装,版本最新:
bash
brew install goreleaser/tap/nfpm如果不介意版本稍旧,也可用 Homebrew 核心仓库版本(安装更快):
bash
brew install nfpm验证安装:
bash
nfpm --version备选:若 brew 安装也遇到 bottle 问题,可直接用 Go 安装,只编译 nFPM 本身,依赖极少:
bashgo install github.com/goreleaser/nfpm/v2/cmd/nfpm@latest
第四步:编写 nfpm.yaml
目录结构假设如下:
.
├── my-service # 交叉编译好的 Linux 二进制
├── my-service.service # systemd 服务文件
└── nfpm.yaml创建 nfpm.yaml:
yaml
name: my-service
arch: amd64
platform: linux
version: 1.0.0
release: "1"
section: default
priority: extra
maintainer: [email protected]
description: My Go Service
vendor: YourName
homepage: https://example.com
contents:
- src: ./my-service
dst: /usr/local/bin/my-service
file_info:
mode: 0755
- src: ./my-service.service
dst: /usr/lib/systemd/system/my-service.service
file_info:
mode: 0644关键点:
mode: 0755确保二进制有执行权限(nFPM 不会自动加执行位)platform: linux与arch: amd64必须与GOOS/GOARCH一致;ARM 目标改为arch: arm64version与release共同构成 RPM 的1.0.0-1版本号
第五步:生成并验证 RPM
一条命令生成:
bash
nfpm pkg --packager rpm --target .当前目录会生成 my-service-1.0.0.x86_64.rpm。--target . 表示输出到当前目录。
验证包内容(需本机有 rpm 命令;没有也不影响 nFPM 打包):
bash
rpm -qpl my-service-1.0.0.x86_64.rpm应能看到 /usr/local/bin/my-service 和 /usr/lib/systemd/system/my-service.service。
踩坑实录:macOS 13 上 brew install rpm 的噩梦
在改用 nFPM 之前,我先尝试了 FPM 方案,需要 brew install rpm 补足 rpmbuild。结果在 macOS 13 上遇到了以下问题:
1. Homebrew 不再为旧 macOS 提供预编译 bottle
日志明确警告:
Warning: You are using macOS 13.
We (and Apple) do not provide support for this old version.
Homebrew no longer builds bottles for this configuration.这意味着所有依赖都要从源码编译。
2. 触发整条 Linux 工具链源码编译
rpm 依赖极多:openssl@4、rust、llvm、[email protected]、gettext、libunistring、lz4、pkgconf、json-c 等。日志显示仅 libunistring 编译 14 分钟、gettext 19 分钟、openssl@4 12 分钟,一个半小时仍未装完。
3. 链接冲突
Error: The `brew link` step did not complete successfully
Could not symlink bin/pkg-config
Target /usr/local/bin/pkg-config already exists.需手动 brew link --overwrite pkgconf 处理。
4. Xcode 与 Command Line Tools 过旧
日志反复警告 Xcode 14.3 过旧、Command Line Tools 需更新,进一步拖慢编译。
结论:在 macOS 13 上通过 Homebrew 装 rpm,等于让 Homebrew 从源码重建半条工具链,时间不可控。这不是机器性能问题,而是 Homebrew 对旧 macOS 的策略变化。换 nFPM 后,安装几分钟完成,打包秒级。
备选方案:Docker + FPM
如果必须使用 FPM 的映射语法或已有 FPM 脚本,最稳的方式是在 Linux 容器里跑,macOS 只负责编译和挂载目录:
bash
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o my-service ./cmd/server
chmod +x my-service
docker run --rm -v "$PWD":/src -w /src rockylinux:9 bash -c '
dnf install -y ruby rubygems rpm-build && \
gem install fpm && \
fpm -s dir -t rpm \
-n my-service -v 1.0.0 --iteration 1 \
--rpm-os linux -a x86_64 \
--description "My Go Service" \
./my-service=/usr/local/bin/my-service \
./my-service.service=/usr/lib/systemd/system/my-service.service
'优点:不污染 macOS 环境,不依赖 brew 的 rpm;缺点:需要 Docker Desktop,首次拉镜像需几分钟。
小结
在 macOS 上为 Go 服务打 RPM 的核心流程(nFPM 方案):
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build交叉编译- 准备 systemd
.service文件 brew install goreleaser/tap/nfpm安装 nFPM(或go install)- 编写
nfpm.yaml,映射二进制与服务文件路径 nfpm pkg --packager rpm --target .生成 RPMrpm -qpl验证包内容
关键教训:macOS 13 上不要用 brew install rpm 走 FPM 路线,它会触发源码编译整条工具链,耗时不可控。优先选纯 Go 的 nFPM,或退一步用 Docker 容器打包。
后续预告:实战篇
本文只覆盖“跑通”这一层。后面我会整理一篇基于实际项目的应用干货,计划包含:
- 真实项目中的目录结构与构建脚本约定(Makefile / shell 一键出包)
- 版本号来源(Git tag / commit 信息)与 nFPM 变量联动
- 多架构(amd64 / arm64)批量出包与制品命名规范
- 安装前后的钩子脚本(创建用户、建目录、迁移配置、平滑重启)
- 与 CI/CD 流水线、制品仓库、灰度发布的衔接方式
敬请期待,发布后会在本文末尾补上链接。
