Bisq 源码构建指南：Gradle 9 Wrapper、JDK 21 工具链与 scripts 启动脚本

Bisq 源码构建指南：Gradle 9 Wrapper、JDK 21 工具链与 scripts 启动脚本

本文围绕 Bisq 官方构建文档 docs/build.md 展开，完整覆盖从克隆仓库（含bitcoind子模块）到执行./gradlew build、再到通过scripts目录启动脚本运行 Bisq Desktop 的全流程；并结合仓库内的 Gradle 配置、构建逻辑插件（build-logic）与启动任务源码，讲解版本固定机制、JDK 工具链解析和startBisqApp任务的底层实现，读完即可独立完成 Bisq 的本地编译与运行。

一、克隆仓库：必须同步 bitcoind 子模块

构建 Bisq 的第一步是克隆仓库。由于 Bisq 的主网依赖一个独立的 Bitcoin Core（bitcoind）子模块用于 regtest 测试环境，克隆时必须带上--recurse-submodules：

git clone --recurse-submodules https://gitcode.com/gh_mirrors/bi/bisq cd bisq

仓库根目录的 .gitmodules 中注册了唯一的子模块：

[submodule "bitcoind"] path = bitcoind url = https://github.com/bisq-network/bitcoind.git

对应地，settings.gradle 中通过includeBuild 'bitcoind'将其作为复合构建纳入工程（第 28 行），而 Gradle 层面的 regtest 任务（如:startFirstRegtestBitcoind）正是依赖这份子模块代码。如果项目此前已克隆、需要更新子模块，执行：

git submodule sync --recursive git submodule update --init --recursive

二、构建前提：JDK 21 与免安装的 Gradle Wrapper

Bisq 的构建文档给出两条"重要注意事项"，其背后都有明确的仓库配置支撑。

2.1 无需手工安装 Gradle

构建文档明确指出：不需要预先安装 Gradle，gradlew脚本会在必要时自动下载并安装。其依据是仓库内置的 Gradle Wrapper，见 gradle/wrapper/gradle-wrapper.properties：

distributionUrl=https\://services.gradle.org/distributions/gradle-9.0.0-bin.zip distributionSha256Sum=8fad3d78296ca518113f3d29016617c7f9367dc005f932bd9d93bf45ba46072b validateDistributionUrl=true

两个细节值得注意：

• distributionUrl将 Gradle 发行版固定为 9.0.0，与 gradle.properties 中releaseBuild.gradleVersion=9.0.0一致，任何机器上跑出的构建都使用同一 Gradle 版本；
• distributionSha256Sum与validateDistributionUrl=true对发行包做 SHA-256 校验，防止下载到被篡改的构建工具；此外 gradle/wrapper/gradle-wrapper.sha256 还分别对gradlew、gradlew.bat、gradle-wrapper.jar、gradle-wrapper.properties四个 Wrapper 文件本身记录了批准的校验和，注释中要求"仅在审查过 Wrapper 变更后才可更新"。

2.2 JDK 必须为 21

构建文档说明"Bisq 目前运行在 JDK 21 上"，并给出三步排查方法：

1. 用javac -version查看当前 JDK 版本；
2. 若系统安装了多个 JDK，用./gradlew --version查看JVM一行，确认 Gradle 实际选用的是哪一个；
3. 若版本不对，可在运行时用JAVA_HOME显式指定（以 Linux 常见路径为例，需按系统实际路径调整）：

JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64 PATH=/usr/lib/jvm/java-21-openjdk-amd64/bin:$PATH ./gradlew clean build

如果没有安装 JDK 21，构建文档建议查看仓库 scripts 目录中的相关脚本，或自行下载 JDK 21。

从源码结构看，"JDK 21"不是口头约定，而是由 Gradle Toolchain 强制约束的：

• 约定式插件 build-logic/commons/src/main/groovy/bisq.java-conventions.gradle 中为所有 Java 模块声明：

  java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }

  这意味着即使本机默认 JDK 版本不符，Gradle 也会按工具链要求选择（或在可用时自动查找）JDK 21 来编译各模块；

• 正式发布构建则完全固定运行时，gradle.properties 中：

  releaseBuild.javaVersion=21.0.6 releaseBuild.javaVendor=Azul Systems, Inc. releaseBuild.gradleVersion=9.0.0

  即发布构建锁定 Azul（Zulu）21.0.6 + Gradle 9.0.0，保证产物可复现。

另外，gradle.properties 还启用了两项对构建行为有实际影响的开关：

org.gradle.caching=true org.gradle.configuration-cache=true

前者开启构建缓存（相同输入的任务直接复用输出），后者开启配置缓存以加快重复构建；同时systemProp.file.encoding=UTF-8、systemProp.user.language=en、systemProp.user.country=US固定了字符集与区域设置，确保跨机器构建行为一致。

三、执行构建：./gradlew build

3.1 构建命令

在 macOS 与 Linux 上执行：

./gradlew build

在 Windows 上执行：

gradlew.bat build

若希望跳过测试以加快构建速度，在命令后追加-x test：

./gradlew build -x test

build任务是标准生命周期任务，会为每个子模块依次执行编译、测试与打包。Bisq 是一个多模块工程，settings.gradle 声明了全部参与构建的模块：proto、proto-grpc（Protobuf 定义）、assets、bridge、btcnodemonitor、common、p2p、core、cli、daemon、desktop、inventory、persistence、restapi、seednode、statsnode、apitest、platform、updater等；依赖版本统一由版本目录 gradle/libs.versions.toml 管理。根 settings.gradle 中pluginManagement还通过includeBuild('build-logic')引入仓库自带的构建逻辑工程，bisq.java-conventions、bisq.application、bisq.javafx、AppStartPlugin、PackagingPlugin等插件都来自这里，这也是无需外部网络获取私有插件的原因。

3.2 构建过程中的依赖签名校验（进阶）

Bisq 启用了 Gradle 依赖校验机制，元数据位于 gradle/verification-metadata.xml，公钥环为 gradle/verification-keyring.keys。根 build.gradle 中注册了resolveAndVerifyDependencies任务用于让 Gradle 校验所有依赖构件，verifyDependencySignaturePolicy（build.gradle）则进一步强制"仅校验和"的未签名依赖必须显式列入 gradle/dependency-checksum-fallback-allowlist.tsv 白名单，否则构建失败。日常开发构建无需额外操作，但了解这一机制有助于理解依赖变更引发的构建失败；完整的说明见 docs/dependency-signature-report.md。

四、运行 Bisq：scripts 目录下的启动脚本

构建完成后，可执行入口位于仓库根目录的scripts文件夹下。构建文档给出的运行方式是：

macOS 与 Linux：

./scripts/desktop

或者显式指定 Java 版本：

env JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64 ./scripts/desktop

Windows：

scripts\desktop.bat

4.1 scripts/desktop 的底层实现

阅读 scripts/desktop 可以发现，它并不是直接java -jar启动，而是对 Gradle 启动任务的一层薄封装：

#!/bin/bash set -e absolute_script_path=$(realpath "$0") scripts_dir_path=$(dirname "$absolute_script_path") cd "${scripts_dir_path}/.." || exit 1 gradle_args=() for arg in "$@"; do gradle_args+=("$(printf '%q' "$arg")") done ./gradlew desktop:startBisqApp --args=\""${gradle_args[*]}"\"

脚本先切回仓库根目录，再把所有附加参数原样转发给desktop:startBisqApp任务的--args。startBisqApp任务由 build-logic/app-start-plugin/src/main/kotlin/bisq/gradle/app_start_plugin/AppStartPlugin.kt 注册，其关键行为有三点：

1. 依赖installDist（第 27 行dependsOn(installDistTask)）：即启动前会先完成该模块的分发安装到build/install/desktop，因此必须先经过gradlew build或等价构建；若installDist/lib不存在，任务会抛出明确的 GradleException 提示先运行installDist（第 48-51 行）；
2. 按工具链选择 JVM（第 28 行与 AppStartPlugin.kt 的getJavaLauncher）：通过JavaToolchainService获取 JDK 21 的 launcher，保证运行环境与 bisq.java-conventions.gradle 的编译工具链一致——这就是构建文档建议在多 JDK 环境下用env JAVA_HOME=...显式指定的原因；
3. 工作目录固定为仓库根目录（第 40 行workingDir = project.projectDir.parentFile）：Bisq 运行时读取的数据目录等均以仓库根为基准，这也是为什么不能随意从其他目录直接启动打包产物。

desktop模块本身的应用入口与 JVM 参数在 desktop/build.gradle 中声明：

application { mainClass = 'bisq.desktop.app.BisqAppMain' applicationDefaultJvmArgs = ['-XX:MaxRAMPercentage=50', '-XX:+UseCompressedOops', '-Xss1280k', '-XX:+UseG1GC', '-XX:MaxHeapFreeRatio=10', '-XX:MinHeapFreeRatio=5', '-XX:+UseStringDeduplication', '-Djava.net.preferIPv4Stack=true', '--add-opens=javafx.controls/javafx.scene.control.skin=ALL-UNNAMED'] }

即主类为bisq.desktop.app.BisqAppMain，堆内存默认限制为物理内存的 50%，使用 G1GC 与字符串去重，并通过--add-opens打开 JavaFX 皮肤包以供第三方库反射访问（Java 9+ 模块系统的必要配置）。

4.2 同一套机制覆盖的全部可运行组件

scripts目录中不止desktop一个入口，从目录列表看，每个可运行组件都成对提供了 POSIX 与 Windows 启动脚本：seednode、statsnode、cli、daemon、restapi、bridge、btcnodemonitor、inventory、apitest等。以 scripts/seednode 为例，其内容与scripts/desktop同构，只是转发到./gradlew seednode:startBisqApp。因此，若构建完想启动种子节点或其他组件，可直接执行./scripts/seednode等对应脚本，附加参数同样会透传给应用。

五、进一步：本地 regtest 网络（localnet）与 IDE 导入

构建文档的"See also"部分指向两份姊妹文档，它们与构建产物直接衔接：

• docs/dev-setup.md：Bisq 开发环境搭建指南，描述如何用 Bitcoin regtest + 本地 P2P 组网，并给出--baseCurrencyNetwork=BTC_REGTEST、--useLocalhostForP2P、--nodePort、--appName等程序参数的完整说明；
• docs/idea-import.md：如何将工程导入 IntelliJ IDEA。

如果目标是搭一个可端到端交易的本地网络，仓库根目录的 Makefile 提供了快捷路径：其头部注释说明 localnet 需要make、bitcoind/bitcoin-cli与 JDK 21；make默认目标执行 Makefile 中的./gradlew :seednode:build :desktop:build，随后./gradlew :startRegtest等目标会拉起 regtest bitcoind、种子节点、mediator 与两个交易实例（startFirstRegtestBitcoind、startRegtestFirstSeednode、startRegtestAlice等任务由根 build.gradle 引入的 RegtestPlugin 注册）。这套流程正是 docs/dev-setup.md 所述组网的自动化版本。

六、相关文档索引

• 本文主体：docs/build.md（克隆、构建、运行与 JDK 说明的官方入口）
• 开发环境组网：docs/dev-setup.md
• IDE 导入：docs/idea-import.md
• 依赖签名报告：docs/dependency-signature-report.md
• 可复现发布构建：docs/reproducible-builds/README.md
• localnet 快捷构建入口：Makefile

适用前提小结：本指南以当前仓库状态为准——Gradle 9.0.0（由 Wrapper 固定）、JDK 21（由 Toolchain 强制，发布构建固定为 Azul 21.0.6）、单一bitcoind子模块（需--recurse-submodules同步）。在构建或运行时遇到版本类报错，优先按javac -version与./gradlew --version的输出核对 JDK/Gradle 实际版本，并用JAVA_HOME显式指定正确的 JDK 21 安装路径。