Bitcoin Core Windows 交叉编译实战：基于 depends + CMake 工具链从构建到 NSIS 安装包

2026-09-04 22:05:51作者：范垣楠Rhoda

本文以 Bitcoin Core 官方的 Windows 构建文档（doc/build-windows.md）为主体，完整讲解在 Linux / WSL 环境下使用 MinGW-w64 交叉编译 Bitcoin Core 的全流程：depends 依赖系统、CMake 工具链文件、二进制安装与裁剪、以及 NSIS 安装包制作。读完本文，你可以复现官方支持的所有 Windows 构建路径，并理解 toolchain.cmake 与 deploy 目标背后的实现机制。

一、官方支持的 Windows 构建方式

在开始操作之前，先明确当前仓库官方文档给出的构建方案矩阵——这是选择工具链的依据：

已知可正常工作的方案（官方测试保障）：

在 Linux 上，使用 MinGW-w64 交叉编译工具链（本文主线）；
在 Windows 上，使用 Windows Subsystem for Linux (WSL) + MinGW-w64；
在 Windows 上，使用 Microsoft Visual Studio，参见 doc/build-windows-msvc.md。

其他可能可行但未经官方测试的方案：

在 Windows 上使用 Cygwin 或 MSYS2 等 POSIX 兼容层应用。

下文聚焦于方案 1 和 2，因为二者共用同一套操作步骤：依赖 depends 系统构建 Windows 目标环境的第三方库，再由 CMake 通过工具链文件完成 Bitcoin Core 本体的交叉编译。

二、工具链与环境要求

文档明确说明：以下步骤在 Ubuntu 和 Debian 上验证有效。执行前需确认：

发行版提供的 g++-mingw-w64-x86-64-posix 包满足 doc/dependencies.md 中规定的最低 GCC 版本要求（当前为 GCC 12.1）；
如果编译带 GUI 的版本（depends 的默认行为，即启用 Qt），至少需要 GCC 13。

安装 Windows 目标所需的工具链（MSVCRT 运行时）：

apt install g++-mingw-w64-x86-64-posix

若希望产出官方格式的 .exe 安装包（deploy 构建目标），还需要 NSIS 安装脚本系统：

apt install nsis

此外，depends/README.md 列出了 depends 系统自身运行所需的构建工具（Ubuntu/Debian）：

apt install cmake curl make patch
# 不构建 GUI（NO_QT=1）时可跳过下面这行
apt install bison g++ ninja-build pkgconf python3 xz-utils

若你的 Ubuntu/Debian 版本没有可用的 MinGW 包，depends/README.md 还给出了一条 Nix 备选路径：安装 nix-bin 后，在仓库根目录运行 NIX_BUILD_SHELL=bash HOST=x86_64-w64-mingw32 nix-shell contrib/devtools/shell-win64-cross.nix（MSVCRT）或 HOST=x86_64-w64-mingw32ucrt（UCRT），仓库中对应的 shell 定义见 contrib/devtools/shell-win64-cross.nix。

三、WSL 用户的关键路径约束

WSL 环境按上游官方说明安装即可（Microsoft 文档中的 WSL 安装步骤）。但有一条必须遵守的硬性约束：

在 WSL 中，Bitcoin Core 源码路径必须位于 WSL 默认挂载的文件系统内（例如 /usr/src/bitcoin），不能放在 /mnt/d/ 下。否则 depends 系统的 autoconf 脚本会失败——也就是说，不能直接使用 Windows 宿主机文件系统上的目录进行构建。

这条约束的本质原因：autoconf 配置脚本依赖 POSIX 语义的路径解析，而 /mnt/* 是 Windows 文件系统的 9P 协议挂载点，其路径与权限行为与 Linux 原生文件系统不同，会导致 autoconf 检测失败。

四、获取源码与完整构建流程

4.1 获取源码

以常规方式克隆 Bitcoin Core 仓库源码并进入目录：

git clone <仓库地址>
cd bitcoin

4.2 第一步：depends 构建 Windows 目标依赖

gmake -C depends HOST=x86_64-w64-mingw32   # 可追加 "-j N" 启用 N 个并行任务

HOST=x86_64-w64-mingw32 是 depends 交叉编译的核心开关（含义见 depends/README.md 的 Cross compilation 章节）：

host-platform-triplet	目标平台
`x86_64-w64-mingw32`	Windows（MSVCRT）
`x86_64-w64-mingw32ucrt`	Windows（UCRT）

HOST 指定后，depends 会在 depends/x86_64-w64-mingw32/ 下构建 Boost、Qt、qrencode、SQLite、ZeroMQ 等全部依赖（可选项见下文 depends 系统一节），并生成 depends/x86_64-w64-mingw32/toolchain.cmake。

4.3 第二步：CMake 配置（必须指定工具链文件）

cmake -B build --toolchain depends/x86_64-w64-mingw32/toolchain.cmake

注意：CMake 默认会忽略 depends 的构建产物，必须通过 --toolchain 显式传入工具链文件，它才会从 depends 目录拾取库、工具与配置。想查看完整的可配置项列表，运行：

cmake -B build -LH

4.4 第三步：编译

cmake --build build     # 可追加 "-j N" 启用 N 个并行任务

五、depends 系统深度解析：toolchain.cmake 是如何生成的

这一节把文档中"参考 depends 目录的 README"这句话落到实处，结合仓库源码说明 Windows 交叉编译配置的真实落地机制。

5.1 主机平台定义

depends/hosts/mingw32.mk 定义了 Windows 目标的基础参数：

优先探测 $(host)-gcc-posix / $(host)-g++-posix 作为交叉编译器（对应 g++-mingw-w64-x86-64-posix 包提供的 x86_64-w64-mingw32-g++-posix）；
Release 构建统一使用 -O2，Debug 构建使用 -O1 -g 并附加 -D_GLIBCXX_DEBUG -D_GLIBCXX_DEBUG_PEDANTIC；
mingw32_cmake_system_name=Windows、mingw32_cmake_system_version=10.0——即交叉产物以 Windows 10 为目标 API 版本。

5.2 工具链文件模板

depends 构建完成后，会基于 depends/toolchain.cmake.in 生成最终的 toolchain.cmake。从该模板可以读出几个关键机制：

交叉编译声明：模板在 @depends_crosscompiling@ 为真时设置 CMAKE_SYSTEM_NAME（Windows）、CMAKE_SYSTEM_PROCESSOR（架构）以及 C/C++ 编译器的 COMPILER_TARGET（即 x86_64-w64-mingw32 三元组），从而触发 CMake 的交叉编译模式；
标志位透传：CFLAGS/CXXFLAGS/LDFLAGS 按 RelWithDebInfo 与 Debug 两种配置分别写入对应的 CMAKE_*_FLAGS_INIT 缓存变量；
搜索路径锁定：CMAKE_FIND_ROOT_PATH 被设为 depends 目录，且 FIND_ROOT_PATH_MODE_LIBRARY/INCLUDE/PACKAGE 全部置为 ONLY——保证 find 函数只在 depends 产物中找库，PROGRAM 置为 NEVER（工具仍从宿主机找）。这就是"工具链文件让 CMake 忽略系统环境"的具体实现；
可选组件联动：模板末尾根据 @qt_packages@、@qrencode_packages@、@zmq_packages@、@wallet_packages@、@usdt_packages@、@ipc_packages@ 是否为空，自动设置 BUILD_GUI、WITH_QRENCODE、WITH_ZMQ、ENABLE_WALLET、WITH_USDT、ENABLE_IPC 缓存变量。也就是说 depends 里跳过的组件，会在 CMake 配置阶段被自动关闭，无需手动传 -D 参数。

5.3 Windows 上的 IPC 默认关闭

depends/Makefile 第 43-44 行有如下逻辑：

# Default NO_IPC value is 1 on Windows
NO_IPC ?= $(if $(findstring mingw32,$(HOST)),1,)

即当 HOST 含 mingw32 时 NO_IPC 默认为 1：不构建 Cap'n Proto 与 libmultiprocess 两个 IPC 组件。这与 depends/README.md 中 NO_IPC 选项说明的 "Default on Windows" 完全一致。

5.4 depends 常用选项速查

以下选项可在 make 时以 make FOO=bar 形式传入（完整说明见 depends/README.md）：

选项	作用
`SOURCES_PATH`	下载的源码存放位置
`BASE_CACHE`	构建好的包缓存位置
`NO_QT`	不下载/构建 Qt 及其依赖（同时关闭 GUI）
`NO_QR`	不构建 qrencode 相关包
`NO_ZMQ`	不构建 ZeroMQ 包
`NO_WALLET`	不构建钱包所需库（SQLite），CMake 侧将设为 `ENABLE_WALLET=OFF`
`NO_IPC`	不构建 Cap'n Proto 与 libmultiprocess，Windows 上默认开启
`DEBUG`	关闭部分优化、启用更多运行时检查
`C_STANDARD` / `CXX_STANDARD`	语言标准，默认 `c11` / `c++20`
`LTO`	启用 LTO 相关配置选项
`LOG`	包级日志落盘，构建出错时自动打印对应日志

另有补充目标：make download-win 可只下载 Windows 构建所需的全部源码而不编译。

六、安装产物到 Windows 目录

构建完成后（WSL 场景下尤其有用），可以把编译好的可执行文件按发行版 .zip 包的目录结构复制到 Windows 盘。例如安装到 c:\workspace\bitcoin：

cmake --install build --prefix /mnt/c/workspace/bitcoin

由于产物携带调试信息，二进制文件可能非常庞大。若不需要调试符号，可在安装时裁剪：

cmake --install build --prefix /mnt/c/workspace/bitcoin --strip

七、制作 NSIS 安装包（deploy 目标）

在第二步 CMake 配置时安装好 NSIS 的前提下，一条命令即可产出 Windows 安装程序：

cmake --build build --target deploy

从源码看，该目标的实现位于 cmake/module/Maintenance.cmake 的 add_windows_deploy_target()，且只在 MINGW 环境且 bitcoin、bitcoin-qt、bitcoind、bitcoin-cli、bitcoin-tx、bitcoin-wallet、bitcoin-util、test_bitcoin 八个目标全部构建完成时才注册（CMakeLists.txt 调用它）。其执行序列是：

将上述八个可执行文件逐一 CMAKE_STRIP 到 release/ 子目录（安装包不含调试符号）；
调用 GenerateWindowsInstaller.cmake（由 cmake/script/GenerateWindowsInstaller.cmake.in 生成），后者先 find_program(MAKENSIS_EXECUTABLE makensis REQUIRED) 强制要求 NSIS 存在，随后用工程变量（版本号、版权声明等）渲染 share/setup.nsi.in 模板为 bitcoin-win64-setup.nsi，最后执行 makensis -V2 bitcoin-win64-setup.nsi 生成 bitcoin-win64-setup.exe。

因此若 deploy 阶段报 makensis 找不到，回到第二节执行 apt install nsis 即可。

八、常见问题与验证手段

autoconf 脚本报错（WSL）：先检查源码是否在 /mnt/* 之下，见第三节路径约束；
CMake 找不到依赖库：确认配置命令带了 --toolchain depends/x86_64-w64-mingw32/toolchain.cmake，且 depends 构建对应的 HOST 与之完全一致；
GUI 编译失败 / 版本报错：确认 MinGW GCC ≥ 13（见第二节）；
验证构建产物：cmake -B build -LH 可查看当前缓存中 BUILD_GUI、ENABLE_WALLET、WITH_ZMQ、WITH_QRENCODE、ENABLE_IPC 等选项的最终取值，应与 depends 构建时传入的 NO_* 选项相互印证；
需要 UCRT 运行时：将 HOST 换为 x86_64-w64-mingw32ucrt，并改用 apt install g++-mingw-w64-ucrt64 工具链，其余步骤不变。

参考路径汇总

内容	路径
本文主体文档	doc/build-windows.md
MSVC 构建说明	doc/build-windows-msvc.md
依赖版本要求（GCC 最低版本等）	doc/dependencies.md
depends 系统文档与选项	depends/README.md
Windows 主机平台定义	depends/hosts/mingw32.mk
NO_IPC 默认值逻辑	depends/Makefile
工具链文件模板	depends/toolchain.cmake.in
deploy 目标实现	cmake/module/Maintenance.cmake
NSIS 安装器生成脚本	cmake/script/GenerateWindowsInstaller.cmake.in
安装包脚本模板	share/setup.nsi.in