Bitcoin Core FreeBSD 构建指南：从依赖安装到 cmake 配置、编译与测试的完整流程

本文基于 Bitcoin Core 仓库中的官方 FreeBSD 构建文档 build-freebsd.md，完整讲解在 FreeBSD 上使用 CMake 构建 bitcoind、命令行工具与 Qt GUI 的全过程：包括必装与可选依赖的安装、关键 CMake 配置项的含义与默认值、编译与单元测试命令，并结合 CMakeLists.txt、depends/hosts/freebsd.mk 与 ci/test/00_setup_env_freebsd_cross.sh 等仓库内证据，说明各选项在源码层面的实际作用。读完后，你可以在最新的 FreeBSD 生产版本上独立完成一次可复现的本地构建，并知道每一项配置开关如何影响最终产物。

支持范围与前提

Bitcoin Core 官方支持所有受支持的 FreeBSD 发行版本。本指南面向最新的 FreeBSD 生产发行版，目标产物包括：

• bitcoind：无界面的守护进程节点；
• 命令行工具：bitcoin-cli、bitcoin-tx、bitcoin-util、bitcoin-wallet 等；
• bitcoin-qt：基于 Qt6 的图形界面。

构建体系当前基于 CMake，从 CMakeLists.txt 的 cmake_minimum_required(VERSION 3.22) 可见最低要求为 CMake 3.22（该下限由 Ubuntu 22.04 / CentOS Stream 9 的工具链版本决定）；同时 CMAKE_CXX_STANDARD 20 表明编译器必须支持 C++20。在 FreeBSD 上安装官方 cmake 软件包即可满足配置阶段要求。

准备工作：安装依赖

所有 pkg install 命令需要以 root 身份执行。

基础必装依赖

pkg install boost-libs cmake git

• boost-libs：Bitcoin Core 使用 Boost 库（构建系统会在 AddBoostIfNeeded.cmake 中按需补检依赖）；
• cmake：构建系统的核心；
• git：获取源码并支持版本信息嵌入。

钱包依赖：SQLite

pkg install sqlite3

SQLite 是钱包功能（ENABLE_WALLET，默认开启）的存储后端。如果不需要钱包，可以直接跳过安装，并在配置时传入 -DENABLE_WALLET=OFF（该选项同时决定 bitcoin-wallet 工具是否构建，见 CMakeLists.txt 中 BUILD_WALLET_TOOL 依赖 ENABLE_WALLET 的定义）。

IPC 依赖：Cap'n Proto

pkg install capnproto

Cap'n Proto 是 IPC（进程间通信）功能所需的序列化格式，详见 multiprocess 设计文档。对应 CMake 选项 ENABLE_IPC 默认为 ON，且仅在非 Windows 平台生效（源码中定义为 cmake_dependent_option(ENABLE_IPC ... ON "NOT WIN32" OFF)），因此在 FreeBSD 上默认启用；不需要该功能时可使用 -DENABLE_IPC=OFF 关闭。

完整的依赖清单可参考 dependencies.md。

可选依赖：GUI（Qt6 与 libqrencode）

Bitcoin Core 的 GUI 基于跨平台的 Qt 框架构建。若要编译图形界面，安装 Qt6 及其工具：

pkg install qt6-base qt6-tools

GUI 还支持将地址编码为二维码（依赖 libqrencode）：

pkg install libqrencode

从源码结构看，二维码支持由 WITH_QRENCODE 控制，默认 ON，但仅在 BUILD_GUI 开启时才生效（cmake_dependent_option(WITH_QRENCODE ... ON "BUILD_GUI" OFF)）。不需要 QR 编码功能时，可在配置阶段传入 -DWITH_QRENCODE=OFF 显式禁用。

此外，CMakeLists.txt 中 WITH_DBUS 的默认条件为「非 Windows/Darwin 且 BUILD_GUI 开启」，即在 FreeBSD 上构建 GUI 时 DBus 支持默认启用，可用于与桌面通知系统集成。

可选依赖：ZeroMQ 通知

Bitcoin Core 可以通过 ZeroMQ 对外发布链上事件通知（详见 zmq 文档）。启用方式：

pkg install libzmq4 pkgconf

然后在配置时传入 -DWITH_ZMQ=ON。注意该选项默认是 OFF，必须显式打开。

测试套件依赖

仓库内置单元测试与功能测试，开发调试时建议运行。测试套件依赖 Python 3：

pkg install python3 databases/py-sqlite3 net/py-pyzmq lsof

• py-sqlite3：功能测试中的钱包与数据库交互；
• py-pyzmq：测试节点间 ZMQ 通知；
• lsof：测试框架用于检查端口占用等场景。

获取源码

安装好 git 与依赖后，克隆 Bitcoin Core 仓库到任意目录，后续所有构建脚本与命令都在该目录内执行：

git clone https://gitcode.com/GitHub_Trending/bi/bitcoin.git

配置（Configuration）

Bitcoin Core 提供大量 CMake 配置项，以下是最常用的两个示例。

启用钱包与 GUI

在已安装 sqlite3 与 Qt6 的前提下：

cmake -B build -DBUILD_GUI=ON

这会启用 BUILD_GUI（默认 OFF）并构建 bitcoin-qt；钱包 ENABLE_WALLET 默认 ON 无需额外指定。

仅构建节点与命令行工具（无钱包、无 GUI）

cmake -B build -DENABLE_WALLET=OFF

查看全部配置项

执行下面命令可列出所有可用缓存变量及其说明：

cmake -B build -LH

结合 CMakeLists.txt 的选项定义，与 FreeBSD 构建相关的开关及默认值整理如下：

选项	默认值	说明
BUILD_DAEMON	ON	构建 bitcoind
BUILD_CLI	ON	构建 bitcoin-cli
BUILD_GUI	OFF	构建 bitcoin-qt，需 Qt6
BUILD_TX / BUILD_UTIL	同 BUILD_TESTS	构建 bitcoin-tx / bitcoin-util
BUILD_TESTS	ON	构建 test_bitcoin 等单元测试可执行文件
ENABLE_WALLET	ON	启用钱包，需 SQLite
ENABLE_IPC	ON（非 Windows）	额外构建多进程 bitcoin-node / bitcoin-gui，需 Cap'n Proto
WITH_ZMQ	OFF	ZeroMQ 通知，需显式开启
WITH_QRENCODE	ON（仅当 BUILD_GUI）	GUI 二维码支持，需 libqrencode
WITH_DBUS	ON（非 Windows/Darwin 且 BUILD_GUI）	桌面通知的 DBus 支持
REDUCE_EXPORTS	OFF	尝试减少可执行文件导出的符号
WITH_CCACHE	ON	自动尝试使用 ccache 加速编译

另外，CMakePresets.json 中还定义了名为 dev-mode 的预设（"Developer mode, with all features/dependencies enabled"），会一次性打开 BUILD_BENCH、BUILD_FUZZ_BINARY 等全部功能，适合开发调试场景使用。

编译与测试

配置完成后执行构建，并按需并行：

cmake --build build     # 追加 "-j N" 以 N 个并行任务编译
ctest --test-dir build  # 追加 "-j N" 以 N 个并行测试执行

• cmake --build build -j $(sysctl -n hw.ncpu) 可充分利用多核；
• ctest 运行的是仓库内置的单元测试（对应 BUILD_TESTS=ON 生成的 test_bitcoin 等目标），开发阶段修改代码后建议执行。

仓库内佐证：FreeBSD 的 CI 交叉构建

除了本机原生构建，仓库的 CI 流水线还在 Ubuntu 容器中通过 clang 交叉工具链直接构建 FreeBSD 目标，可以印证原生构建的路径与 CI 一致：

• ci/test/00_setup_env_freebsd_cross.sh 使用 x86_64-unknown-freebsd 主机三元组、FreeBSD 15.1 SDK 与 clang/lld 工具链，配置参数为 --preset=dev-mode -DCMAKE_LINKER_TYPE=LLD -DREDUCE_EXPORTS=ON -DWITH_USDT=OFF，并执行 install 目标验证安装流程；
• depends/hosts/freebsd.mk 定义了 depends 交叉构建系统中 FreeBSD 的主机配置，如 x86_64_freebsd_CC=clang -m64、freebsd_cmake_system_name=FreeBSD，说明 FreeBSD 工具链在依赖构建体系中同样基于 clang。

从这些脚本可以看出：CI 与文档推荐的原生构建在 CMake 选项层面完全一致，差别仅在于工具链（clang + LLD + REDUCE_EXPORTS=ON）与运行环境，本地构建可按需参考这些参数。

小结

在 FreeBSD 上构建 Bitcoin Core 的流程可以归纳为四步：

1. pkg install 安装 boost-libs、cmake、git，并按需加装 sqlite3、capnproto、qt6-base qt6-tools、libqrencode、libzmq4 pkgconf、Python 测试依赖；
2. git clone 获取源码；
3. 用 cmake -B build 加 -DBUILD_GUI=ON / -DENABLE_WALLET=OFF / -DWITH_ZMQ=ON 等开关完成配置，用 cmake -B build -LH 查看全部可选项；
4. cmake --build build -j N 编译，ctest --test-dir build -j N 验证。

所有配置开关的默认值与依赖关系均可在 CMakeLists.txt 中查证，构建细节可进一步结合 dependencies.md、multiprocess.md 与 zmq 文档 深入阅读。