Skip to main content
本构建指南适用于修改 ClickHouse 本身的贡献者。如果你不修改 ClickHouse 源代码，可以按照快速入门中的说明安装预构建的 ClickHouse。
ClickHouse 可在以下平台上构建：
  • x86_64
  • AArch64
  • PowerPC 64 LE (Experimental)
  • s390/x (Experimental)
  • RISC-V 64 (Experimental)

​
前提条件

以下教程基于 Ubuntu Linux，但经过适当调整后，也适用于其他任何 Linux 发行版。 建议用于开发的最低 Ubuntu 版本为 24.04 LTS。 本教程假定你已在本地检出 ClickHouse 仓库及其所有子模块。

​
安装前置条件

首先，请参阅通用的前置条件文档。 ClickHouse 使用 CMake 和 Ninja 进行构建。 你也可以选择安装 ccache，以便在构建时复用已编译的对象文件。

​
安装 Clang 编译器

要在 Ubuntu/Debian 上安装 Clang，请使用 LLVM 提供的自动安装脚本，脚本可从这里获取。
对于其他 Linux 发行版，请确认是否可以安装 LLVM 的任一预编译软件包。 截至 2026 年 2 月，需要使用 Clang 21 或更高版本。 不支持 GCC 或其他编译器。

​
安装 Rust 编译器 (可选)

Rust 是 ClickHouse 的可选依赖。 如果未安装 Rust，ClickHouse 的某些功能将不会被编译进去。
首先，请按照官方 Rust 文档 中的步骤安装 rustup。 与 C++ 依赖类似，ClickHouse 使用 vendoring 来精确控制安装内容，并避免依赖第三方服务 (例如 crates.io registry) 。 虽然在 release 模式下，原则上任何较新的 rustup 工具链版本都应能配合这些依赖正常工作，但如果你打算启用 sanitizers，则必须使用与 CI 中所用版本完全相同的 std 版本 (我们也会为此 vendor 相应的 crate) ：

​
构建 ClickHouse

我们建议在 ClickHouse 内创建一个单独的目录 build，用于存放所有构建制品：
你可以为不同的构建类型使用多个不同的目录 (例如 build_release、build_debug 等) 。 可选：如果安装了多个版本的编译器，也可以指定要使用的具体编译器。
出于开发用途，建议使用调试构建。 与发布构建相比，调试构建的编译器优化级别 (-O) 更低，因此能提供更好的调试体验。 此外，类型为 LOGICAL_ERROR 的内部异常会立即导致程序崩溃，而不是以更平缓的方式失败。
如果你想使用 gdb 等调试器，请在上述命令中添加 -D DEBUG_O_LEVEL="0"，以移除所有编译器优化，因为这些优化可能会影响 gdb 查看或访问变量。
运行 ninja 开始构建：
如果要构建所有二进制文件 (包括实用工具和测试) ，请直接运行不带参数的 ninja：
您可以使用 -j 参数控制并行构建任务的数量：
clickhouse-server、clickhouse-client 以及类似的二进制文件，在构建完成后都是 programs/ 目录中指向 clickhouse 可执行文件的符号链接。:::tip CMake 为上述命令提供了简写方式：

​
运行 ClickHouse 可执行文件

构建成功后，可在 ClickHouse/<build_dir>/programs/ 中找到该可执行文件： ClickHouse 服务器会尝试在当前目录中查找配置文件 config.xml。 你也可以通过命令行参数 -C 指定配置文件。 要使用 clickhouse-client 连接到 ClickHouse 服务器，请打开另一个终端，进入 ClickHouse/build/programs/，然后运行 ./clickhouse client。 如果你在 macOS 或 FreeBSD 上收到 Connection refused 消息，请尝试将主机地址指定为 127.0.0.1：

​
高级选项

​
最小构建

如果您不需要第三方库提供的功能，还可以进一步加快构建过程：
如果出现问题，就只能你自己处理了…… Rust 需要联网。要禁用 Rust 支持：

​
运行 ClickHouse 可执行文件

你可以用编译后的 ClickHouse 二进制文件替换系统中已安装的生产版 ClickHouse 二进制文件。 为此，请按照官网说明在你的机器上安装 ClickHouse。 接下来，运行：
请注意，clickhouse-client、clickhouse-server 等都是指向共用 clickhouse 可执行文件的符号链接。 你也可以使用系统中已安装的 ClickHouse 软件包里的配置文件来运行你自定义构建的 ClickHouse 可执行文件：

​
在任何 Linux 上构建

在 OpenSUSE Tumbleweed 上安装前置条件：
在 Fedora Rawhide 上安装前置条件：

​
在 Docker 中构建

你可以使用以下方式，在与 CI 类似的环境中于本地运行任意构建：
其中，BUILD_JOB_NAME 是 CI 报告中显示的作业名称，例如 “Build (arm_release)”、“Build (amd_debug)” 此命令会拉取包含所有必需依赖的相应 Docker image clickhouse/binary-builder， 并在其中运行构建脚本：./ci/jobs/build_clickhouse.py 构建输出将放在 ./ci/tmp/ 中。 它同时适用于 AMD 和 ARM 架构，除已安装 requests 模块的 Python 和 Docker 外，无需任何额外依赖。
最后修改于 2026年6月12日