Bitcoin Core Linux 安装与运行环境完全指南：glibc 要求、GUI 依赖安装与构建前置条件

本文基于 Bitcoin Core 仓库中的 doc/INSTALL_linux.md 展开，系统讲解在 Linux 系统上部署 Bitcoin Core 的关键前置条件：glibc 最低版本要求、bitcoin-qt GUI 基于 Qt 6 的 xcb 平台插件运行依赖，以及在 Debian/Ubuntu 与 Fedora 上安装 libfontconfig、libfreetype 的具体命令，并结合仓库 CMake 构建配置与依赖文档说明如何验证与满足这些条件，帮助你在 Linux 上顺利完成安装、构建和运行 Bitcoin Core。

一、通用运行时要求：glibc 2.31 及以上

INSTALL_linux.md 首先明确了一条通用运行时要求：

Bitcoin Core requires glibc (GNU C Library) 2.31 or newer.

这条约束适用于所有 Bitcoin Core 的 Linux 发布二进制文件。其背景可以从仓库的依赖文档中得到印证：doc/dependencies.md 在 “Required / Runtime” 依赖表中将 glibc 列为唯一的必备运行时依赖，最低版本同样为 2.31：

依赖	类型	最低要求
glibc	运行时	2.31

也就是说，只要你的发行版自带 glibc ≥ 2.31（例如 Debian 11 Bullseye、Ubuntu 20.04 Focal 及之后的主流发行版），即可直接运行官方发布的 Linux 二进制；反之，在 glibc 更老的系统上，发布二进制将无法启动。这一要求自 glibc 2.31 起生效，与仓库当前开发版本的构建目标保持一致，因此在验证部署环境时应以 INSTALL_linux.md 中的这条声明为准。

如何检查当前系统的 glibc 版本，可以使用以下任一命令：

ldd --version | head -n 1
# 或
strings /lib64/libc.so.6 | grep -E '^GLIBC_[0-9]+' | sort -Vu | tail -n 1

第一条命令会输出类似 ldd (GNU libc) 2.35 的信息；第二条命令直接探测 libc 动态库中导出的最高 Glibc 符号版本。输出中出现的最高 GLIBC_x.xx 版本即当前系统可用的 glibc 能力上限，只要不低于 2.31 即可满足 Bitcoin Core 的运行时要求。

二、GUI（bitcoin-qt）的运行依赖：Qt 6 + xcb 平台插件

INSTALL_linux.md 的第二部分说明：GUI 可执行文件 bitcoin-qt 基于 Qt 6 框架，并且使用 xcb QPA（Qt Platform Abstraction）平台插件运行于 X11。这句话包含两个关键信息：

1. Qt 版本：Qt 6。仓库的 doc/dependencies.md 在可选构建依赖中列明 Qt 最低要求为 6.2，与官方二进制打包的 Qt 6 一致。
2. 窗口系统：X11（通过 xcb）。可以推断，bitcoin-qt 的发布构建并不附带 Wayland 原生后端，在无 X11 会话的纯 Wayland 桌面中需要配合 XWayland 运行。

在 Qt 6 中，QPA 插件决定程序与显示系统的对接方式：xcb 插件负责 X11 通信（包括字体、输入法、剪贴板等子系统）。bitcoin-qt 在启动时会按 QT_QPA_PLATFORM 环境变量（默认为 xcb）加载对应插件，若缺少 X11 连接则会报错退出。这与仓库 src/qt/CMakeLists.txt 中构建时引入 xcbglintegrations 模块的做法相互印证——GUI 构建从一开始就按 xcb 平台插件组织链接。

2.1 运行时库依赖：libfontconfig 与 libfreetype

文档明确列出 bitcoin-qt 的运行时库依赖为：

• libfontconfig
• libfreetype

这两个库分别负责：

• Fontconfig：系统的字体配置与查找框架，Qt 的字体枚举（QFontDatabase 等）在 Linux 上依赖它来发现可用字体；
• FreeType：字体渲染引擎，负责将字体文件光栅化为位图。

Qt 6 的 xcb 平台插件在链接层面依赖这两个库做文本渲染。若系统缺少它们，bitcoin-qt 启动时会出现类似 error while loading shared libraries: libfontconfig.so.1 的动态链接错误，或界面文字无法正常显示。仓库中 depends/packages/fontconfig.mk 与 depends/packages/freetype.mk 正是官方交叉/depends 构建环境引入这两个库的配方，而 doc/dependencies.md 在 “Optional / Runtime” 表中给出其最低版本：Fontconfig 2.6、FreeType 2.3.0。发行版自带的版本普遍高于此要求。

2.2 按发行版安装依赖

INSTALL_linux.md 给出了两大主流包管理器的安装命令，可直接复制执行：

Debian / Ubuntu 及其衍生发行版（apt）：

sudo apt install libfontconfig1 libfreetype6

Fedora（dnf）：

sudo dnf install fontconfig freetype

文档同时提示：其他系统请查阅各自发行版的文档。这里给出几个常见发行版的包名对照，便于检索（具体包名请以发行版包索引为准）：

发行版	包管理器	对应包名
Debian / Ubuntu	apt	libfontconfig1、libfreetype6
Fedora	dnf	fontconfig、freetype
Arch	pacman	fontconfig、freetype2
openSUSE	zypper	fontconfig、freetype

安装完成后，可通过动态链接信息验证 bitcoin-qt 的依赖是否全部满足：

ldd $(command -v bitcoin-qt) | grep -E 'fontconfig|freetype|not found'

若没有任何 not found 输出，且 libfontconfig、libfreetype 均指向已安装的库文件，说明 GUI 运行依赖已就绪。

三、构建视角：这些要求如何体现在仓库构建配置中

虽然 INSTALL_linux.md 聚焦于“安装运行”，但对照仓库的构建系统可以完整理解上述要求的来由，也便于自行从源码构建。

3.1 CMake 与工具链基线

INSTALL_linux.md 未展开构建要求，仓库根目录的 CMakeLists.txt 则给出了当前开发版本构建的硬性基线：

• CMake ≥ 3.22（cmake_minimum_required(VERSION 3.22)，见 CMakeLists.txt），且明确禁止 in-source build（CMakeLists.txt）；
• C++20 标准（CMakeLists.txt）；
• 编译器最低版本来自 doc/dependencies.md：GCC 12.1 或 Clang 17.0。

构建开关与产物也值得注意：BUILD_BITCOIN_BIN、BUILD_DAEMON（bitcoind）、BUILD_CLI 默认开启，而 BUILD_GUI 默认关闭（CMakeLists.txt），即只有显式 -DBUILD_GUI=ON 并安装 Qt 6 等依赖后才会构建 bitcoin-qt。这解释了为何多数 Linux 节点只运行 bitcoind，而 GUI 用户需要额外准备 Qt 6 与 xcb 相关库。

3.2 依赖安装的两条路径

doc/dependencies.md 指出依赖有两种满足方式：按平台文档手动安装，或使用仓库自带的 depends 系统自行编译。对于 Linux 平台的通用构建步骤，可参考 doc/build-unix.md；依赖包的打包配方集中在 depends/packages/，其中与本文主题直接相关的有：

• depends/packages/fontconfig.mk、depends/packages/freetype.mk：GUI 运行时依赖；
• depends/packages/qt.mk、depends/packages/qrencode.mk：Qt 6 与二维码库（GUI 构建时引入）；
• depends/packages/sqlite.mk：钱包所需的 SQLite（可选功能）。

使用 depends 交叉构建时，最终产物会将这些库静态/内嵌打包，因此发布二进制只需要系统提供 glibc ≥ 2.31 以及上文列出的 libfontconfig、libfreetype 等少量共享库——这正是 INSTALL_linux.md 只列出这两个 GUI 运行时依赖的原因。

3.3 Qt 发现的 CMake 实现细节

-DBUILD_GUI=ON 时，Qt 的发现逻辑由 cmake/module/FindQt.cmake 封装：它包装 find_package(Qt6 ...)，统一处理不同构建环境的搜索路径并输出标准日志。而具体组件（Core、Gui、Network、Widgets 等）与 xcb 相关模块的链接，则定义在 src/qt/CMakeLists.txt 中——从源码结构看，xcbglintegrations 等 xcb 集成模块被显式加入 bitcoin-qt 的链接目标，这与 INSTALL_linux.md 中 “uses the xcb QPA platform plugin to run on X11” 的描述一一对应。

四、安装部署检查清单

结合 INSTALL_linux.md 的全部要点，Linux 部署 Bitcoin Core 前可按下表自查：

检查项	适用对象	要求	验证命令
glibc 版本	bitcoind / 全部二进制	≥ 2.31	ldd --version
X11 会话	bitcoin-qt	有 X11 或 XWayland	echo $DISPLAY
libfontconfig	bitcoin-qt	已安装	ldd $(command -v bitcoin-qt) | grep fontconfig
libfreetype	bitcoin-qt	已安装	ldd $(command -v bitcoin-qt) | grep freetype
发行版安装命令	Debian/Ubuntu	sudo apt install libfontconfig1 libfreetype6	—
发行版安装命令	Fedora	sudo dnf install fontconfig freetype	—

五、小结

• 所有 Linux 二进制：仅需系统 glibc ≥ 2.31（INSTALL_linux.md、doc/dependencies.md 一致确认）；
• GUI（bitcoin-qt）：基于 Qt 6，经 xcb 平台插件运行于 X11；系统需额外提供 libfontconfig 与 libfreetype，Debian/Ubuntu 用 sudo apt install libfontconfig1 libfreetype6，Fedora 用 sudo dnf install fontconfig freetype 一键补齐；
• 从源码构建：需 CMake ≥ 3.22、C++20、GCC ≥ 12.1 或 Clang ≥ 17，BUILD_GUI 默认关闭，GUI 构建路径由 cmake/module/FindQt.cmake 与 src/qt/CMakeLists.txt 实现，依赖配方见 depends/packages/。

按上述顺序验证 glibc、补齐 GUI 依赖并检查 ldd 输出，即可在 Linux 上稳妥地安装和运行 Bitcoin Core。