Bitcoin Core 在 Unix 下从源码构建完全指南：CMake 流程、依赖安装与可选特性开关

本文基于 Bitcoin Core 官方构建文档 build-unix.md 整理，覆盖在 Unix 系统上从源码构建 Bitcoin Core 的完整流程：CMake 配置与编译命令、编译内存不足时的调优手段、Debian/Fedora/Alpine/Arch 四大发行版的依赖包清单，以及钱包、IPC、ZeroMQ、USDT 追踪、Qt GUI 等可选特性的开关方式。读完本文，你可以独立完成一次生产级构建，并能结合 CMakeLists.txt 源码理解每个构建选项的默认值与依赖检查逻辑。

构建流程：三步 CMake 命令

Bitcoin Core 目前使用 CMake 作为构建系统（参见 INSTALL.md，其内容指向 doc/build-*.md 系列平台文档）。在 Unix 下，最基本的构建只有三步：

cmake -B build

如果想查看当前仓库支持的全部可配置选项，可以加 -LH 参数列出完整的缓存变量及说明：

cmake -B build -LH

然后编译并（可选）安装：

cmake --build build    # 追加 "-j N" 可开启 N 个并行编译任务
cmake --install build  # 可选

从 CMakeLists.txt 可以看到，配置阶段结束时 CMake 会打印一份 “Configure summary”，逐行列出最终生效的可执行文件目标（bitcoin、bitcoind、bitcoin-node（multiprocess）、bitcoin-qt、bitcoin-cli、bitcoin-tx、bitcoin-util、bitcoin-wallet）、可选特性（wallet support、ZeroMQ、IPC、Embedded ASMap、USDT tracing、QR code、DBus）与测试目标（test_bitcoin、bench_bitcoin、fuzz binary），并报告交叉编译状态与 C++ 编译器版本。这份摘要非常适合在 CI 或排错时用来核对选项是否按预期生效。

构建选项总览：默认值来自 CMakeLists.txt

-LH 列出的选项在源码中集中定义于 CMakeLists.txt。与本文档相关的核心选项及其默认值如下（以当前仓库为准）：

选项	默认值	说明（源自 CMake 帮助文本）
ENABLE_WALLET	ON	Enable wallet. 关闭后不需要 SQLite
BUILD_GUI	OFF	Build bitcoin-qt executable.
WITH_ZMQ	OFF	Enable ZMQ notifications.
ENABLE_IPC	ON（仅非 Windows）	额外构建 multiprocess 版 bitcoin-node 和 bitcoin-gui 可执行文件，依赖 Cap'n Proto
WITH_USDT	OFF	Enable tracepoints for Userspace, Statically Defined Tracing.
WITH_QRENCODE	ON（依赖 BUILD_GUI）	Enable QR code support.
WITH_DBUS	ON（Linux 且 BUILD_GUI 时）	Enable DBus support.
BUILD_TESTS	ON	构建 test_bitcoin 等单元测试可执行文件
BUILD_BENCH / BUILD_FUZZ_BINARY	OFF	基准测试 / 模糊测试二进制

这些默认值解释了官方文档的写法：ZMQ 需要显式 -DWITH_ZMQ=ON，GUI 需要显式 -DBUILD_GUI=ON，而 IPC 在 Unix 上默认开启、因此默认构建就要求安装 Cap'n Proto。

从源码结构看，选项之间存在联动关系：启用 BUILD_FOR_FUZZING 时会关闭几乎其余所有目标（见 CMakeLists.txt）；BUILD_GUI_TESTS 只有在 BUILD_GUI 和 BUILD_TESTS 同时开启时才生效；BUILD_WALLET_TOOL 跟随 ENABLE_WALLET。这些联动由 cmake_dependent_option 实现，配置失败时可以直接看 summary 摘要定位原因。

编译内存需求与三种缓解手段

C++ 编译器非常吃内存。文档建议编译 Bitcoin Core 时至少预留 1.5 GB 内存。内存不足的系统有三种缓解手段，按文档给出的顺序：

1. 调低 gcc 内存参数（通过 CMAKE_CXX_FLAGS 追加）：

   cmake -B build -DCMAKE_CXX_FLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768"
   

2. 跳过调试信息。默认构建类型为 RelWithDebInfo，默认编译标志是 -O2 -g，可以把 -g 换成 -g0：

   cmake -B build -DCMAKE_CXX_FLAGS_RELWITHDEBINFO="-O2 -g0"
   

3. 改用 clang 代替默认的 gcc（clang 通常更省资源）：

   cmake -B build -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang
   

另外，构建系统默认启用 ccache（WITH_CCACHE 选项默认为 ON，见 CMakeLists.txt），重复编译时能显著加速并间接降低峰值资源压力。

依赖安装：四大发行版的包清单

依赖有两种获取方式：使用发行版包管理器安装，或用仓库自带的 depends 系统自行编译（后者支持交叉编译，详见 depends/README.md 与 description.md）。后几列为可选特性所需。

包管理器	必需构建依赖	SQLite（钱包）	Cap'n Proto（IPC）	ZMQ [1]	USDT	Qt 和 libqrencode（GUI）
Debian / Ubuntu（apt）	build-essential cmake python3 libboost-dev	libsqlite3-dev	libcapnp-dev capnproto	libzmq3-dev pkgconf	systemtap-sdt-dev	qt6-base-dev qt6-tools-dev qt6-l10n-tools qt6-tools-dev-tools libgl-dev qt6-wayland libqrencode-dev
Fedora（dnf）	gcc-c++ cmake make python3 boost-devel	sqlite-devel	capnproto capnproto-devel	zeromq-devel pkgconf	systemtap-sdt-devel	qt6-qtbase-devel qt6-qttools-devel qt6-qtwayland qrencode-devel
Alpine（apk）	build-base cmake linux-headers python3 boost-dev	sqlite-dev	capnproto capnproto-dev	zeromq-dev	不支持	qt6-qtbase-dev qt6-qttools-dev libqrencode-dev
Arch（pacman）	gcc make cmake python3 boost	sqlite	capnproto	zeromq	systemtap	qt6-base qt6-tools qt6-wayland qrencode

[1] 部分 ZMQ 包不附带 CMake 配置文件，此时需要额外安装 pkgconf 或 pkg-config。

对 Debian "oldstable" 或更早的 Ubuntu LTS 版本，可能需要选择更新的编译器版本，具体版本要求见 dependencies.md。

编译器与最低版本要求

doc/dependencies.md 列出了当前仓库的硬性版本要求：

• 编译器：Clang ≥ 17.0 或 GCC ≥ 12.1；
• 构建依赖：Boost ≥ 1.74.0、CMake ≥ 3.22；
• 运行时：glibc ≥ 2.31；
• 可选依赖最低版本：Cap'n Proto ≥ 0.7.1、libmultiprocess ≥ v7.0-pre1、Python ≥ 3.10、Qt ≥ 6.2、ZeroMQ ≥ 4.0.0、SQLite ≥ 3.7.17。

如果你的发行版预装编译器低于上述版本，升级编译器比降级代码更可靠。

可选特性与源码中的依赖检查

各可选特性在 CMake 配置阶段会按需触发 find_package 检查，这与上面依赖表中的“后几列为可选”一一对应：

• 钱包（SQLite）：ENABLE_WALLET 开启时，CMake 会执行 find_package(SQLite3 3.7.17 REQUIRED)（见 CMakeLists.txt）。关闭钱包即跳过该检查——这是 disable-wallet 模式省掉 SQLite 依赖的底层原因。
• IPC（Cap'n Proto）：Cap'n Proto 是 multiprocess 功能所需，用法见 multiprocess.md。不需要 IPC 时编译加 -DENABLE_IPC=OFF。注意 ENABLE_IPC 是非 Windows 平台默认开启的选项（CMakeLists.txt），所以默认构建在 Unix 上需要安装 libcapnp-dev/capnproto；使用 depends 系统时则由 NO_IPC=1 变量控制，无需再单独传参。
• ZeroMQ：ZMQ 通知功能的二进制通过 -DWITH_ZMQ=ON 编译，需要 libzmq（源码中要求 ≥ 4.0.0，见 CMakeLists.txt）。
• USDT 追踪：User-Space, Statically Defined Tracing 需要 systemtap-sdt 开发包，并通过 -DWITH_USDT=ON 启用（见 CMakeLists.txt）。
• Qt GUI：Bitcoin Core 内置基于 Qt 框架的跨平台 GUI。编译 GUI 需安装 Qt 相应组件与 libqrencode，并传 -DBUILD_GUI=ON；不打算使用 GUI 可直接跳过。文档还建议额外安装 Qt Wayland 平台插件以适配现代桌面环境。从源码看（CMakeLists.txt），GUI 构建会查找 Qt 6.2 的 Core Gui Widgets LinguistTools 组件，ENABLE_WALLET 开启时追加 Network，WITH_DBUS 开启时追加 DBus——这也解释了包表中 GUI 一列为什么包含 qttools 等开发包。
• QR 编码：GUI 依赖 libqrencode 来把地址编码为二维码。若不需要二维码功能，可用 -DWITH_QRENCODE=OFF 关闭该特性后编译 GUI。

Disable-wallet 模式

当目标只是运行一个不带钱包的 P2P 节点时，可以用 disable-wallet 模式编译：

cmake -B build -DENABLE_WALLET=OFF

此时构建不再依赖 SQLite。文档同时指出，disable-wallet 模式下依然可以挖矿——使用 getblocktemplate RPC 调用即可，因此该模式适用于矿池工作节点、纯同步节点等无钱包部署场景。

使用 depends 系统替代系统包

如果不想安装发行版包（尤其是交叉编译场景），可以用仓库内置的 depends 构建系统。以 Ubuntu/Debian 为例（引自 depends/README.md）：

apt install cmake curl make patch
# 不构建 GUI（配合 NO_QT=1）时可跳过下列包
apt install bison g++ ninja-build pkgconf python3 xz-utils
make        # 为当前架构+OS 构建依赖

depends 会生成一个 toolchain 文件，cmake 可通过 --toolchain=depends/$HOST_PLATFORM/toolchain.cmake 从中读取库路径与开关状态，从而免去逐个传递 -DENABLE_IPC=ON 之类的参数（见 doc/multiprocess.md 中的完整示例）。依赖包定义位于 depends/packages 目录，每个 .mk 文件（如 sqlite.mk、zeromq.mk、qt.mk）对应一个可自编译的依赖。

小结

在 Unix 上构建 Bitcoin Core 的核心路径就是 cmake -B build → cmake --build build，关键在于按部署需求选择依赖与开关：

• 最小 P2P 节点：安装“必需构建依赖” + Cap'n Proto，-DENABLE_WALLET=OFF，无需 SQLite；
• 标准全功能节点：加上 libsqlite3-dev，保持默认钱包与 IPC；
• 需要事件推送：-DWITH_ZMQ=ON 并安装 libzmq3-dev pkgconf；
• 需要 GUI：-DBUILD_GUI=ON 并安装 Qt6 与 libqrencode-dev 全家桶。

配置完成后务必检查 CMake 输出的 Configure summary（对应 CMakeLists.txt 的打印逻辑），确认 wallet support、IPC、ZeroMQ、USDT、QR code 各项状态与预期一致。更多平台细节可参考同目录下的 build-osx.md、build-freebsd.md、build-netbsd.md、build-openbsd.md 等文档。