Bitcoin Core 28.2 维护版发布详解：构建、可复现打包与稳定性修复全景解读

2026-09-06 19:12:09作者：毕习沙Eudora

Bitcoin Core 28.2 是针对 28.x 系列发布的一个维护版本（maintenance release），包含若干新特性、大量缺陷修复与性能改进，并同步更新了多语言翻译。本文以仓库内 doc/release-notes/release-notes-28.2.md 为骨架，围绕升级流程、系统兼容性以及 Build / Test / Tracing / Doc / Misc 五大类共 13 项变更展开深度解读，并结合本仓库的 Guix 打包脚本、depends 构建配方、RPC 测试与 tracing 工具的源码逐一印证，帮助读者全面掌握该版本在发布签名、可复现构建与代码质量层面的具体改动。

一、版本定位与升级指南

28.2 属于补丁级（patch）维护发布，这意味着它在 28.x 功能基线之上不引入大的协议或架构变更，重点落在修复回归、完善工具链与消除技术债上。发布说明同时指出：它包含新特性、各类缺陷修复与性能改进，以及更新的翻译文件；若发现问题可通过项目的 Issue 追踪器反馈，并建议订阅安全与更新通知渠道以第一时间获得通告。

从旧版本升级的正确操作

升级方式与传统比特币内核版本保持一致，官方文档给出的标准步骤为：

若正在运行旧版本，首先彻底关闭节点进程；
等待进程完全退出（部分情况下可能需要数分钟，例如大量数据需要落盘或索引重建）；
按平台替换程序文件：
- Windows：直接运行新版安装包（installer）；
- macOS：覆盖 /Applications/Bitcoin-Qt；
- Linux：覆盖 bitcoind 与 bitcoin-qt 可执行文件。

发布说明还特别强调两点兼容性前提：

支持跨 EOL 直升级：从一个已到达生命周期终点（End of Life）的旧版本直接升级到 28.2 是可行的，但如果数据目录需要迁移，启动过程可能耗时较长；
旧钱包版本普遍兼容：历史旧版本的 Bitcoin Core 钱包文件在新版本中一般仍可正常加载。

从源码构建与可复现验证

如果需要自行构建 28.2 对应产物以核对官方二进制，本仓库提供了完整的可复现构建（bootstrappable build）方案。构建与签名编排入口位于 contrib/guix，其 guix-codesign 等脚本正是 28.2 构建链中签名改造的核心载体（详见下文对 #31407 的分析）。具体用法参见 contrib/guix/INSTALL.md 与 contrib/guix/libexec/codesign.sh。

二、系统兼容性要求

28.2 的兼容性基线沿用了该系列的标准声明：

平台	支持范围
Linux	内核 3.17+（被支持且经过广泛测试）
macOS	11.0+
Windows	Windows 7 及以上
其他类 UNIX 系统	理论上可运行，但测试频度较低

发布说明明确提示：不建议在不支持的系统上使用 Bitcoin Core。这一兼容性声明对运维者的价值在于：升级前应核对宿主系统的内核/系统版本，避免在超出官方测试矩阵的环境上运行导致无法预期的行为。

三、Notable Changes：构建（Build）链路的 7 项修复

28.2 变更最密集的领域是构建系统，这与其"维护版"定位一致——补丁版通常集中回填持续集成与发布流水线中发现的问题。

#31407：Guix 产物全面签名——macOS 公证与全平台代码签名

这是 28.2 中最具影响力的变更：在 Guix 可复现构建流程中为 macOS App Bundle 增加公证（notarize），并为所有 macOS 与 Windows 二进制实施代码签名。

在本仓库的发布基础设施中可以找到完整的实现证据：

contrib/guix/libexec/codesign.sh 按宿主平台分支处理签名：
- Windows（mingw）：使用 osslsigncode attach-signature -in <bin> -out ... -sigin codesignatures/win/<bin>.pem 将外部生成的分离式签名（detached signature）回贴到 *.exe；
- macOS（darwin）：使用 signapple apply dist/Bitcoin-Qt.app codesignatures/osx/<HOST>/dist/Bitcoin-Qt.app 对 App Bundle 打签名，并对 */bin/*、*/libexec/* 下的所有可执行文件逐一执行 signapple apply。
contrib/guix/manifest_codesign.scm 中定义了 Guix 侧所需的 python-signapple 等签名工具依赖；
调用入口 contrib/guix/guix-codesign 及其说明文档 contrib/guix/README.md 给出了完整操作方式。

签名操作的配套用法（摘自仓库文档）如下，注意 DETACHED_SIGS_REPO 是必填环境变量，用于指定存放当前版本分离式签名的 Git 仓库目录；由于仅 Windows 与 macOS 产物需要签名，HOSTS 的合理默认值为 x86_64-w64-mingw32 x86_64-apple-darwin arm64-apple-darwin：

env DETACHED_SIGS_REPO=<path/to/bitcoin-detached-sigs> ./contrib/guix/guix-codesign

配合仓库中的签名字节码归属与哈希汇总逻辑（见 contrib/guix/guix-attest，其中区分 noncodesigned 与 codesigned 产物片段并分别维护 SHA256SUMS），28.2 标志着发布管线在交付物完整性可审计上进一步收紧。

#31500：修复 NetBSD 平台 libevent 依赖编译

该 PR 修复了 depends 交叉环境中 libevent 包在 NetBSD 上的编译失败问题。NetBSD 并非官方广泛测试平台，此类修复保证了构建配方在更多 BSD 系宿主上的一致性，降低社区自建发布的门槛。

#31627：修正 depends 中的格式/缩进问题

这是 depends 构建配方（位于 depends/packages）的一处纯排版性修正，消除可能误导维护者的空格不一致，属于低风险代码卫生类变更。

#32070：构建使用 make < 3.82 的 define 指令语法

构建脚本改用 make 3.82 之前版本兼容的 define 指令语法。这一改动扩大了构建宿主的 make 版本兼容面，保证在较老但仍被广泛部署的 make 版本上（例如部分长期维护发行版默认版本）也能正确展开多行变量定义，避免因语法版本差异导致构建期宏展开异常。

#32439：Guix 上游仓库向 Codeberg 迁移的适配

Guix 官方 Git 仓库发生托管迁移后，本仓库的构建编排相应跟进。可在源码中直接观察到该适配的痕迹：

contrib/guix/libexec/prelude.bash 中的 guix time-machine 调用已改为 --url=https://codeberg.org/guix/guix.git；
contrib/guix/INSTALL.md 中安装指引同步指向新的 Guix 仓库地址（含 channel 更新示例）。

这一改动对可复现构建的可信链条至关重要：时间机器（time-machine）所固定的 Guix 提交必须能够从稳定可达的镜像获取，否则发行版构建与复核都会受阻。

#32568：xproto 安装改用 "mkdir -p"

depends 中 xproto 包（对应配方 depends/packages/xproto.mk）的安装步骤改用 mkdir -p 创建目标目录，避免在父目录已存在或需递归创建时安装失败，使配方对既有/全新构建目录两种状态都保持幂等。

#32693：修复 freetype 的 CMake 兼容错误

freetype 依赖配方（depends/packages/freetype.mk）在采用 CMake 构建路径时存在兼容性错误，28.2 修复了该问题，确保 Qt/GUI 依赖链在 CMake 时代的 depends 构建体系中可稳定产出。这与仓库整体向 CMake 构建迁移（参见根目录 CMakeLists.txt、CMakePresets.json 及 depends/README.md 对 toolchain.cmake 的用法）保持步调一致。

四、测试（Test）链路的两项维护

#32286：RPC 测试将 CLI 返回的空字符串处理为 None：在 Python 侧 RPC/CLI 测试框架中，将命令行工具可能返回的空字符串统一规范化映射为 None，消除了空串与空值语义混用导致的偶发断言误判，提升了 test/functional 中跨平台输出解析的健壮性。
#32336：抑制 bpfcc 上游的 -Wduplicate-decl-specifier 告警：在引入 BPF 编译器集合（bpfcc）相关测试构建时，对上游第三方头文件触发的重复声明说明符告警进行抑制，避免第三方代码的告警污染本项目的构建输出与告警门禁（CI 的 lint/告警检查见 ci 目录下的流水线配置）。

五、Tracing 与文档类变更

#31623：重命名 tracing 脚本中的 MIN 宏为 TRACEPOINT_TEST_MIN

P2P 报文日志的 USDT/BCC 追踪脚本原先定义了一个名为 MIN 的宏，容易与内核头文件或其他依赖中的同名宏发生冲突。28.2 将其重命名为 _TRACEPOINT_TEST_MIN 并保留原有语义。可在仓库的 contrib/tracing/log_raw_p2p_msgs.py 中看到该宏的现状：

// A min() macro. Prefixed with _TRACEPOINT_TEST to avoid collision with other MIN macros.
#define _TRACEPOINT_TEST_MIN(a,b) ({ __typeof__ (a) _a = (a); __typeof__ (b) _b = (b); _a < _b ? _a : _b; })

其实际用途是在 bpf_probe_read_user 中限制一次性读取的报文长度不超过 MAX_MSG_DATA_LENGTH，例如：

bpf_probe_read_user(&msg->msg, _TRACEPOINT_TEST_MIN(msg->msg_size, MAX_MSG_DATA_LENGTH), pmsg);

这一改动对使用该脚本观测 P2P 原始报文（contrib/tracing/log_raw_p2p_msgs.py）的用户是透明的，但显著提升了脚本在内核跟踪环境中的可移植性。

#32003：移除文档中关于 macOS 自签名的说明

随着 #31407 将 macOS 产物纳入正式代码签名与公证流程，旧的"开发者自行对 macOS 包做自签名（self-sign）以便本机运行"的提示已不再必要，28.2 从文档中移除了该说明。相关打包与签名配套资料可参考 contrib/macdeploy/README.md 与 contrib/guix/README.md。

六、杂项（Misc）：许可年份与代码卫生

#31611：许可证文本更新至 2025：随年份更迭将仓库各文件头部版权声明中的许可证年份同步到 2025，属于例行合规维护（许可证全文见根目录 COPYING）。
#32187：移除 final 类上多余的 virtual 修饰符：对 ~CZMQNotificationInterface 析构函数做重构清理。在 src/zmq/zmqnotificationinterface.h 中可看到该类的定义已标记为 final，其析构函数为普通（非 virtual）声明，对应的实现位于 src/zmq/zmqnotificationinterface.cpp：

class CZMQNotificationInterface final : public CValidationInterface
{
    ...
    ~CZMQNotificationInterface();
};

从源码结构看，由于类本身 final，继承树上不再存在派生类，原先多余的 virtual 说明符会被编译器判定为冗余（可能触发相关告警），移除后语义不变但代码更精确，也消除了因"虚析构 + final"组合引发的静态分析噪音。

七、总结：28.2 的升级收益与注意事项

综合来看，Bitcoin Core 28.2 是一次聚焦"发布工程与代码质量"的维护版更新，其收益可归纳为三点：

产物可信度提升：macOS 公证 + Windows/macOS 全量代码签名（#31407），叠加 Guix 上游镜像适配（#32439），使官方二进制的来源验证与可复现复核更加可靠；
构建兼容面扩大：针对 NetBSD、老版本 make、xproto 与 freetype 的 depends 配方修复（#31500/#32070/#32568/#32693）降低了跨平台自建发布的门槛；
工程质量回填：RPC 测试空值语义统一（#32286）、tracing 宏冲突消除（#31623）与代码卫生清理（#32187）共同减少了长期维护中的隐性风险。

对运行 28.x 系列节点的运维者而言，可遵循官方升级步骤直接覆盖替换 bitcoind / bitcoin-qt；对希望复核或自行签名的开发者，则建议重点阅读本仓库 contrib/guix/README.md 中关于 guix-build、guix-codesign 与 codesign.sh 的完整流程。若已在此前的 28.x 版本上运行，本次升级平滑、无数据格式迁移负担；若从更早的 EOL 版本直升，请为数据目录迁移预留足够启动时间。