Bitcoin Core 构建依赖管理详解：版本基线、depends 构建系统与 CMake 集成

本文基于 Bitcoin Core 官方依赖文档 doc/dependencies.md，系统梳理 Bitcoin Core 的编译器与依赖版本基线、各项依赖（Boost、Qt、SQLite、ZeroMQ 等）对应源码中的 CMake 集成位置，并结合 depends/README.md 讲清如何用 depends 系统自编译全部依赖、配置 toolchain 以及跨平台交叉编译。读完本文，你可以对照仓库实际代码确认每项依赖的最小版本依据，并独立完成 Bitcoin Core 的依赖构建与配置。

依赖总览：官方版本基线

doc/dependencies.md 是 Bitcoin Core 的依赖权威清单，将依赖划分为三大类：

类别	说明
编译器	必须满足 Clang、GCC、Xcode CLT 或 MSVC 中任一工具链的最低版本
必需依赖（Required）	构建期（Boost、CMake）与运行期（glibc）
可选依赖（Optional）	构建期（Cap'n Proto、libmultiprocess、Python、Qt、qrencode、SQLite、systemtap、ZeroMQ）与运行期（Fontconfig、FreeType）

文档同时指出两种获取依赖的途径：查阅各平台的安装说明（仓库 doc/ 下的构建文档，如 doc/INSTALL_linux.md），或使用仓库自带的 depends 系统自编译并缓存依赖。下文逐一展开，并给出每一项最低版本在 CMake 构建系统与实际构建包中的落地证据。

编译器要求

Bitcoin Core 要求以下工具链之一（满足最低版本即可）：

工具链	最低版本
Clang	17.0
GCC	12.1
Xcode CLT	16.2
MSVC	18.3

从源码结构看，这个版本底线并非仅停留在文档中。根 CMakeLists.txt 将语言标准固定为 C++20：

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

且 cmake/module/CheckCXXFeatures.cmake 会在配置阶段编译一段探测代码，强制验证编译器支持"聚合类型的类模板参数推导（CTAD）"——这是 src/util/overloaded.h 中 Overloaded 辅助模板所依赖的 C++ 特性。若编译器过旧，会直接终止配置并提示：

Compiler lacks Class Template Argument Deduction (CTAD) for aggregates.
This C++ feature is required for src/util/overloaded.h.
You are probably using an old compiler version
The recommended compiler versions can be checked in
doc/dependencies.md#compiler.

也就是说，文档中的编译器版本表与构建系统的硬性检查形成闭环：低于基线的编译器在 cmake 配置阶段即被拒绝。

在使用 depends 构建依赖时，编译器还受 CC/CXX（目标编译器）与 build_CC/build_CXX（本机构建工具编译器，如 native_capnp、native_qt）控制。默认值为 Linux 上 gcc/g++、macOS/FreeBSD/OpenBSD 上 clang/clang++（见 depends/builders/ 下的各平台 .mk）。若系统缺少默认编译器，可全部改用 Clang：

make -C depends build_CC=clang build_CXX=clang++ CC=clang CXX=clang++

必需依赖

构建期：Boost 与 CMake

依赖	最低版本
Boost	1.74.0
CMake	3.22

CMake 3.22 的底线直接体现在根 CMakeLists.txt：

# Ubuntu 22.04 LTS Jammy Jellyfish, https://wiki.ubuntu.com/Releases, EOSS in June 2027:
#  - CMake 3.22.1, https://packages.ubuntu.com/jammy/cmake
cmake_minimum_required(VERSION 3.22)

注释说明选择 3.22 的依据是 Ubuntu 22.04 LTS（支持到 2027 年 6 月）自带的 CMake 3.22.1，即以长期支持发行版的工具链版本作为下限。

Boost 1.74.0 的检查位于 cmake/module/AddBoostIfNeeded.cmake：

find_package(Boost 1.74.0 REQUIRED CONFIG)

从源码结构看，Bitcoin Core 实际只使用 Boost 头文件（Boost::headers），并显式定义 BOOST_MULTI_INDEX_DISABLE_SERIALIZATION 关闭 multi_index 序列化；对旧版 Boost 还会探测并追加 BOOST_NO_CXX98_FUNCTION_BASE，以抑制对 C++17 已移除的 std::unary_function 的使用警告。depends 构建路径下，depends/packages/boost.mk 将版本精确锁定为 1.91.0-1，仅构建 multi_index 与 test 组件（BOOST_TEST_HEADERS_ONLY=ON，不构建 MPI/Python 支持），并安装到独立的 boost/include 目录，避免被其他依赖的 -I 路径意外引入。

运行期：glibc

依赖	最低版本
glibc	2.31

运行 Bitcoin Core 的 Linux 系统需提供 glibc 2.31 及以上版本（对应 Ubuntu 20.04 及更新发行版的常见基线）。该约束由依赖文档声明，用于保证二进制在目标发行版上可运行；在 depends 交叉编译时，depends 内部会自行构建一套目标平台的 glibc，使产物对目标系统版本的敏感度显著降低。

可选依赖：构建期

可选依赖对应 Bitcoin Core 的各扩展能力（GUI、钱包、IPC 多进程、USDT 跟踪、ZeroMQ 通知等），CMake 中均有对应的开关选项，配置摘要（Configure summary）会逐项打印其最终状态。

Cap'n Proto 与 libmultiprocess（IPC 多进程）

依赖	最低版本	用途
Cap'n Proto	0.7.1	IPC 多进程架构
libmultiprocess	v7.0-pre1	IPC 多进程架构

CMake 中对应 根 CMakeLists.txt：

cmake_dependent_option(ENABLE_IPC "Build multiprocess bitcoin-node and bitcoin-gui executables in addition to monolithic bitcoind and bitcoin-qt executables." ON "NOT WIN32" OFF)
cmake_dependent_option(WITH_EXTERNAL_LIBMULTIPROCESS "Build with external libmultiprocess library instead of with local git subtree when ENABLE_IPC is enabled." OFF "ENABLE_IPC" OFF)

从源码结构看，ENABLE_IPC 在非 Windows 平台默认开启，Windows 平台默认关闭；WITH_EXTERNAL_LIBMULTIPROCESS 默认使用仓库内嵌的 git subtree，仅在开发 libmultiprocess 本身时才切换到外部库。depends 侧 depends/packages/native_capnp.mk 将 Cap'n Proto 锁定为 1.5.0，depends/packages/native_libmultiprocess.mk 锁定 libmultiprocess 的对应版本。注意 Cap'n Proto 属于 native_ 包——它作为构建期工具运行在构建机上，而非目标机的运行时依赖。

Python（脚本与测试）

依赖	最低版本	用途
Python	3.10	构建脚本与功能测试

CMakeLists.txt 中查找 Python 解释器并设置了两项搜索策略以兼容 Python 版本管理器（如 pyenv 的 shim）：

set(Python3_FIND_FRAMEWORK LAST CACHE STRING "")
set(Python3_FIND_UNVERSIONED_NAMES FIRST CACHE STRING "")
find_package(Python3 3.10 COMPONENTS Interpreter)
if(NOT TARGET Python3::Interpreter)
  list(APPEND configure_warnings "Minimum required Python not found.")
endif()

值得注意的细节：缺少 Python 3.10 不会导致配置失败，而是进入 configure_warnings 列表，在配置摘要末尾以 WARNING 形式提醒——因为 Python 主要用于脚本与测试（test/functional/ 下 300 余个功能测试均为 Python 编写），而非可执行文件的运行前提。

Qt 与 qrencode（GUI）

依赖	最低版本	用途
Qt	6.2	图形界面（bitcoin-qt）
qrencode	无最低版本限制	GUI 二维码显示

构建 GUI 时（BUILD_GUI=ON），CMakeLists.txt 会按功能拼装 Qt 组件列表：基础为 Core Gui Widgets LinguistTools，启用钱包时追加 Network，启用 DBus 时追加 DBus，构建 GUI 测试时追加 Test：

find_package(Qt 6.2 MODULE REQUIRED COMPONENTS ${qt_components})

qrencode 由 WITH_QRENCODE 选项控制（依赖 BUILD_GUI，见 CMakeLists.txt）。depends 侧分别由 depends/packages/qt.mk（版本细节在 depends/packages/qt_details.mk）与 depends/packages/qrencode.mk（锁定 4.1.1）提供。

SQLite（钱包）

依赖	最低版本	用途
SQLite	3.7.17	钱包数据库（ENABLE_WALLET）

[CMakeLists.txt](https://gitcode.com/GitHub_Trending/bi/bitcoin/blob/dc0395c5858a1d55239b82a834e5075cf2069219/CMakeLists.txt?utm_source=gitcode_repo_files#L117-L140 区间内的 L229-L240) 中：

option(ENABLE_WALLET "Enable wallet." ON)
...
find_package(SQLite3 3.7.17 REQUIRED)

depends 构建路径下 depends/packages/sqlite.mk 将 SQLite 锁定为 3.50.4（版本号 3500400 即 3.50.4），并通过大量裁剪编译宏得到精简单一钱包库：

$(package)_config_opts = --disable-shared --disable-readline --disable-rtree
$(package)_config_opts += --disable-fts4 --disable-fts5
$(package)_cppflags += -DSQLITE_DQS=0 -DSQLITE_DEFAULT_MEMSTATUS=0 -DSQLITE_OMIT_DEPRECATED
$(package)_cppflags += -DSQLITE_OMIT_SHARED_CACHE -DSQLITE_OMIT_JSON -DSQLITE_LIKE_DOESNT_MATCH_BLOBS
$(package)_cppflags += -DSQLITE_OMIT_DECLTYPE -DSQLITE_OMIT_PROGRESS_CALLBACK -DSQLITE_OMIT_AUTOINIT
$(package)_cppflags += -DSQLITE_OMIT_LOAD_EXTENSION

只构建静态库 libsqlite3.a，并关闭共享缓存、JSON 扩展、动态加载扩展等钱包不需要的能力，减小攻击面与体积。

systemtap（USDT 跟踪）

依赖	用途
systemtap	USDT 用户态静态跟踪

对应 CMake 选项 WITH_USDT（CMakeLists.txt，默认 OFF），开启后通过 cmake/module/FindUSDT.cmake 查找系统tap 工具链；depends 侧 depends/packages/systemtap.mk 锁定 5.3。该依赖用于在编译期植入跟踪探针（tracepoint），配合 doc/tracing.md 中介绍的系统tap 脚本观测节点行为。

ZeroMQ（通知）

依赖	最低版本	用途
ZeroMQ (libzmq)	4.0.0	区块/内存池事件通知，见 doc/zmq.md

WITH_ZMQ 选项（默认 OFF，CMakeLists.txt）开启后执行 find_package(ZeroMQ 4.0.0 MODULE REQUIRED)。查找逻辑封装在 cmake/module/FindZeroMQ.cmake 中：优先使用 CMake 原生 find_package（Config 模式）并统一别名为 zeromq 目标；若未找到，则回退到 pkg-config 查询 libzmq>=4.0.0。depends 侧 depends/packages/zeromq.mk 锁定 4.3.5。

可选依赖：运行期

GUI 在 Linux 上运行还依赖两个系统字体库（仅在构建/运行 bitcoin-qt 时需要）：

依赖	最低版本
Fontconfig	2.6
FreeType	2.3.0

depends 构建路径下分别由 depends/packages/fontconfig.mk（锁定 2.12.6）与 depends/packages/freetype.mk（锁定 2.11.1）提供，并作为 Qt 的依赖链被一并构建。

depends 构建系统实操

depends/README.md 给出了各平台的完整安装与构建流程。以 Ubuntu/Debian 为例：

# 基础工具
apt install cmake curl make patch
# GUI 构建额外需要（若计划用 NO_QT=1 构建则跳过）
apt install bison g++ ninja-build pkgconf python3 xz-utils

# 为当前架构 + 操作系统构建依赖
make

其他平台的对应命令为：

平台	命令
macOS	brew install cmake make ninja 后执行 gmake
FreeBSD	pkg install bash cmake curl gmake（GUI 另加 bison ninja pkgconf python3）后执行 gmake
NetBSD	pkgin install bash cmake curl gmake perl 后执行 gmake
OpenBSD	pkg_add bash cmake curl gmake gtar（GUI 另加 bison ninja）后执行 gmake
Alpine	apk add bash build-base cmake curl make patch（GUI 另加 bison linux-headers samurai pkgconf python3）后执行 make

关键：必须通过 toolchain 文件接入 depends 产物

depends/README.md 特别强调：CMake 默认会忽略 depends 的输出。构建完成后，depends 会生成类似 depends/x86_64-pc-linux-gnu/toolchain.cmake 的文件，配置 Bitcoin Core 时必须显式传入：

cmake -B build --toolchain depends/x86_64-pc-linux-gnu/toolchain.cmake

该 toolchain 文件负责把 depends 中编译好的库、工具与编译定义（对应根 CMakeLists.txt 中注入的 DEPENDS_COMPILE_DEFINITIONS 等变量）传递给主构建。

构建选项

运行 make 时可追加参数（make FOO=bar），与依赖项的对应关系如下：

变量	作用
SOURCES_PATH	下载源码的存放位置
BASE_CACHE	已构建包的缓存位置
SDK_PATH	SDK 路径（macOS 使用）
FALLBACK_DOWNLOAD_PATH	主下载源失败时的回退路径
C_STANDARD / CXX_STANDARD	C/C++ 标准版本，默认 c11 / c++20
NO_BOOST	不下载/构建/缓存 Boost
NO_QT	不下载/构建/缓存 Qt 及其依赖
NO_QR	不构建 qrencode 相关包
NO_ZMQ	不构建 ZeroMQ 相关包
NO_WALLET	不构建钱包所需库（SQLite）
NO_USDT	不构建 USDT 跟踪所需包
NO_IPC	不构建 Cap'n Proto 与 libmultiprocess（Windows 下默认如此）
DEBUG	关闭部分优化并启用更多运行时检查
LTO	启用 LTO 所需选项（不向 FLAGS 追加 -flto 相关参数）
LOG	单包文件日志，构建失败时自动打印
HOST_ID_SALT / BUILD_ID_SALT	生成 host/build 包 id 时的可选盐值

文档还指出一个联动机制：若某些包被跳过（例如 make NO_WALLET=1），depends 生成的 toolchain 会相应设置 CMake 缓存变量（此时 -DENABLE_WALLET=OFF），使主构建自动与依赖集保持一致。

交叉编译

通过 HOST=host-platform-triplet 构建其他架构/操作系统，路径自动配置、无需其他选项：

make HOST=x86_64-w64-mingw32 -j4

常用 triplet 包括：

Triplet	目标
i686-linux-gnu	Linux x86 32 位
x86_64-linux-gnu	Linux x86 64 位
x86_64-w64-mingw32 / x86_64-w64-mingw32ucrt	Windows（MSVCRT / UCRT）
x86_64-apple-darwin / arm64-apple-darwin	Intel / ARM macOS
arm-linux-gnueabihf / aarch64-linux-gnu	Linux ARM 32/64 位
powerpc64-linux-gnu / powerpc64le-linux-gnu	Linux POWER 64 位（大/小端）
riscv32-linux-gnu / riscv64-linux-gnu	Linux RISC-V 32/64 位
s390x-linux-gnu	Linux S390X

各目标的前置工具链安装（如 Windows 交叉编译需 g++-mingw-w64-x86-64-posix 或 g++-mingw-w64-ucrt64，Linux 各架构需对应 g++-*-linux-gnu 与 binutils 包，macOS 交叉编译需 Clang 18+ 与 macOS SDK）在 depends/README.md 中均有完整清单。此外还提供只取源码不构建的目标：make download、download-osx、download-win、download-linux。

小结：文档、depends 与 CMake 的三层对应关系

依赖	文档最低版本	depends 锁定版本	CMake 检查位置
Boost	1.74.0	1.91.0-1	AddBoostIfNeeded.cmake
CMake	3.22	—	CMakeLists.txt
glibc	2.31	depends 内部自编译	—
Cap'n Proto	0.7.1	1.5.0	ENABLE_IPC（CMakeLists.txt）
libmultiprocess	v7.0-pre1	subtree 内嵌	WITH_EXTERNAL_LIBMULTIPROCESS
Python	3.10	—	CMakeLists.txt
Qt	6.2	qt_details 锁定	CMakeLists.txt
qrencode	N/A	4.1.1	WITH_QRENCODE
SQLite	3.7.17	3.50.4	CMakeLists.txt
systemtap	N/A	5.3	WITH_USDT
ZeroMQ	4.0.0	4.3.5	CMakeLists.txt
Fontconfig	2.6	2.12.6	GUI 依赖链
FreeType	2.3.0	2.11.1	GUI 依赖链

实践要点：配置前先用 cmake --version 与 g++ --version（或 clang --version）对照本文基线；用 depends 构建时必须通过 --toolchain depends/<triplet>/toolchain.cmake 接入产物；按需组合 NO_QT/NO_WALLET/NO_ZMQ 等开关，并留意 toolchain 随之设置的 CMake 变量（如 -DENABLE_WALLET=OFF），即可让最终构建出的可执行文件（bitcoind、bitcoin-cli、bitcoin-qt 等）能力集与依赖集严格一致。