Bitcoin Core Windows 交叉编译实战基于 depends CMake 工具链从构建到 NSIS 安装包【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin本文以 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/Debianapt install cmake curl make patch # 不构建 GUINO_QT1时可跳过下面这行 apt install bison g ninja-build pkgconf python3 xz-utils若你的 Ubuntu/Debian 版本没有可用的 MinGW 包depends/README.md 还给出了一条 Nix 备选路径安装nix-bin后在仓库根目录运行NIX_BUILD_SHELLbash HOSTx86_64-w64-mingw32 nix-shell contrib/devtools/shell-win64-cross.nixMSVCRT或HOSTx86_64-w64-mingw32ucrtUCRT仓库中对应的 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 bitcoin4.2 第一步depends 构建 Windows 目标依赖gmake -C depends HOSTx86_64-w64-mingw32 # 可追加 -j N 启用 N 个并行任务HOSTx86_64-w64-mingw32是 depends 交叉编译的核心开关含义见 depends/README.md 的 Cross compilation 章节host-platform-triplet目标平台x86_64-w64-mingw32WindowsMSVCRTx86_64-w64-mingw32ucrtWindowsUCRTHOST指定后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 -LH4.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-posixRelease 构建统一使用-O2Debug 构建使用-O1 -g并附加-D_GLIBCXX_DEBUG -D_GLIBCXX_DEBUG_PEDANTICmingw32_cmake_system_nameWindows、mingw32_cmake_system_version10.0——即交叉产物以 Windows 10 为目标 API 版本。5.2 工具链文件模板depends 构建完成后会基于 depends/toolchain.cmake.in 生成最终的toolchain.cmake。从该模板可以读出几个关键机制交叉编译声明模板在depends_crosscompiling为真时设置CMAKE_SYSTEM_NAMEWindows、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不构建 Capn Proto 与 libmultiprocess 两个 IPC 组件。这与 depends/README.md 中NO_IPC选项说明的 Default on Windows 完全一致。5.4 depends 常用选项速查以下选项可在make时以make FOObar形式传入完整说明见 depends/README.md选项作用SOURCES_PATH下载的源码存放位置BASE_CACHE构建好的包缓存位置NO_QT不下载/构建 Qt 及其依赖同时关闭 GUINO_QR不构建 qrencode 相关包NO_ZMQ不构建 ZeroMQ 包NO_WALLET不构建钱包所需库SQLiteCMake 侧将设为ENABLE_WALLETOFFNO_IPC不构建 Capn Proto 与 libmultiprocessWindows 上默认开启DEBUG关闭部分优化、启用更多运行时检查C_STANDARD/CXX_STANDARD语言标准默认c11/c20LTO启用 LTO 相关配置选项LOG包级日志落盘构建出错时自动打印对应日志另有补充目标make download-win可只下载 Windows 构建所需的全部源码而不编译。六、安装产物到 Windows 目录构建完成后WSL 场景下尤其有用可以把编译好的可执行文件按发行版.zip包的目录结构复制到 Windows 盘。例如安装到c:\workspace\bitcoincmake --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.mdMSVC 构建说明doc/build-windows-msvc.md依赖版本要求GCC 最低版本等doc/dependencies.mddepends 系统文档与选项depends/README.mdWindows 主机平台定义depends/hosts/mingw32.mkNO_IPC 默认值逻辑depends/Makefile工具链文件模板depends/toolchain.cmake.indeploy 目标实现cmake/module/Maintenance.cmakeNSIS 安装器生成脚本cmake/script/GenerateWindowsInstaller.cmake.in安装包脚本模板share/setup.nsi.in【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Bitcoin Core Windows 交叉编译实战：基于 depends + CMake 工具链从构建到 NSIS 安装包
Bitcoin Core Windows 交叉编译实战基于 depends CMake 工具链从构建到 NSIS 安装包【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin本文以 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/Debianapt install cmake curl make patch # 不构建 GUINO_QT1时可跳过下面这行 apt install bison g ninja-build pkgconf python3 xz-utils若你的 Ubuntu/Debian 版本没有可用的 MinGW 包depends/README.md 还给出了一条 Nix 备选路径安装nix-bin后在仓库根目录运行NIX_BUILD_SHELLbash HOSTx86_64-w64-mingw32 nix-shell contrib/devtools/shell-win64-cross.nixMSVCRT或HOSTx86_64-w64-mingw32ucrtUCRT仓库中对应的 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 bitcoin4.2 第一步depends 构建 Windows 目标依赖gmake -C depends HOSTx86_64-w64-mingw32 # 可追加 -j N 启用 N 个并行任务HOSTx86_64-w64-mingw32是 depends 交叉编译的核心开关含义见 depends/README.md 的 Cross compilation 章节host-platform-triplet目标平台x86_64-w64-mingw32WindowsMSVCRTx86_64-w64-mingw32ucrtWindowsUCRTHOST指定后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 -LH4.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-posixRelease 构建统一使用-O2Debug 构建使用-O1 -g并附加-D_GLIBCXX_DEBUG -D_GLIBCXX_DEBUG_PEDANTICmingw32_cmake_system_nameWindows、mingw32_cmake_system_version10.0——即交叉产物以 Windows 10 为目标 API 版本。5.2 工具链文件模板depends 构建完成后会基于 depends/toolchain.cmake.in 生成最终的toolchain.cmake。从该模板可以读出几个关键机制交叉编译声明模板在depends_crosscompiling为真时设置CMAKE_SYSTEM_NAMEWindows、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不构建 Capn Proto 与 libmultiprocess 两个 IPC 组件。这与 depends/README.md 中NO_IPC选项说明的 Default on Windows 完全一致。5.4 depends 常用选项速查以下选项可在make时以make FOObar形式传入完整说明见 depends/README.md选项作用SOURCES_PATH下载的源码存放位置BASE_CACHE构建好的包缓存位置NO_QT不下载/构建 Qt 及其依赖同时关闭 GUINO_QR不构建 qrencode 相关包NO_ZMQ不构建 ZeroMQ 包NO_WALLET不构建钱包所需库SQLiteCMake 侧将设为ENABLE_WALLETOFFNO_IPC不构建 Capn Proto 与 libmultiprocessWindows 上默认开启DEBUG关闭部分优化、启用更多运行时检查C_STANDARD/CXX_STANDARD语言标准默认c11/c20LTO启用 LTO 相关配置选项LOG包级日志落盘构建出错时自动打印对应日志另有补充目标make download-win可只下载 Windows 构建所需的全部源码而不编译。六、安装产物到 Windows 目录构建完成后WSL 场景下尤其有用可以把编译好的可执行文件按发行版.zip包的目录结构复制到 Windows 盘。例如安装到c:\workspace\bitcoincmake --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.mdMSVC 构建说明doc/build-windows-msvc.md依赖版本要求GCC 最低版本等doc/dependencies.mddepends 系统文档与选项depends/README.mdWindows 主机平台定义depends/hosts/mingw32.mkNO_IPC 默认值逻辑depends/Makefile工具链文件模板depends/toolchain.cmake.indeploy 目标实现cmake/module/Maintenance.cmakeNSIS 安装器生成脚本cmake/script/GenerateWindowsInstaller.cmake.in安装包脚本模板share/setup.nsi.in【免费下载链接】bitcoinBitcoin Core integration/staging tree项目地址: https://gitcode.com/GitHub_Trending/bi/bitcoin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
