> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-home-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Linux 系统上从源码构建 ClickHouse 的分步指南

# 如何在 Linux 上构建 ClickHouse

<Info>
  **本构建指南适用于修改 ClickHouse 本身的贡献者。**

  如果你不修改 ClickHouse 源代码，可以按照[快速入门](/zh/get-started/setup/install)中的说明安装预构建的 ClickHouse。
</Info>

ClickHouse 可在以下平台上构建：

* x86\_64
* AArch64
* PowerPC 64 LE (Experimental)
* s390/x (Experimental)
* RISC-V 64 (Experimental)

<div id="assumptions">
  ## 前提条件
</div>

以下教程基于 Ubuntu Linux，但经过适当调整后，也适用于其他任何 Linux 发行版。
建议用于开发的最低 Ubuntu 版本为 24.04 LTS。

本教程假定你已在本地检出 ClickHouse 仓库及其所有子模块。

<div id="install-prerequisites">
  ## 安装前置条件
</div>

首先，请参阅通用的[前置条件文档](/zh/resources/develop-contribute/introduction/developer-instruction)。

ClickHouse 使用 CMake 和 Ninja 进行构建。

你也可以选择安装 ccache，以便在构建时复用已编译的对象文件。

```bash theme={null}
sudo apt-get update
sudo apt-get install build-essential git cmake ccache python3 ninja-build nasm yasm gawk lsb-release wget software-properties-common gnupg
```

<div id="install-the-clang-compiler">
  ## 安装 Clang 编译器
</div>

要在 Ubuntu/Debian 上安装 Clang，请使用 LLVM 提供的自动安装脚本，脚本可从[这里](https://apt.llvm.org/)获取。

```bash theme={null}
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 21
```

对于其他 Linux 发行版，请确认是否可以安装 LLVM 的任一[预编译软件包](https://releases.llvm.org/download.html)。

截至 2026 年 2 月，需要使用 Clang 21 或更高版本。
不支持 GCC 或其他编译器。

<div id="install-the-rust-compiler-optional">
  ## 安装 Rust 编译器 (可选)
</div>

<Note>
  Rust 是 ClickHouse 的可选依赖。
  如果未安装 Rust，ClickHouse 的某些功能将不会被编译进去。
</Note>

首先，请按照官方 [Rust 文档](https://www.rust-lang.org/tools/install) 中的步骤安装 `rustup`。

与 C++ 依赖类似，ClickHouse 使用 vendoring 来精确控制安装内容，并避免依赖第三方服务 (例如 `crates.io` registry) 。

虽然在 release 模式下，原则上任何较新的 rustup 工具链版本都应能配合这些依赖正常工作，但如果你打算启用 sanitizers，则必须使用与 CI 中所用版本完全相同的 `std` 版本 (我们也会为此 vendor 相应的 crate) ：

```bash theme={null}
rustup toolchain install nightly-2026-03-22
rustup default nightly-2026-03-22
rustup component add rust-src
```

<div id="build-clickhouse">
  ## 构建 ClickHouse
</div>

我们建议在 `ClickHouse` 内创建一个单独的目录 `build`，用于存放所有构建制品：

```sh theme={null}
mkdir build
cd build
```

你可以为不同的构建类型使用多个不同的目录 (例如 `build_release`、`build_debug` 等) 。

可选：如果安装了多个版本的编译器，也可以指定要使用的具体编译器。

```sh theme={null}
export CC=clang-21
export CXX=clang++-21
```

出于开发用途，建议使用调试构建。
与发布构建相比，调试构建的编译器优化级别 (`-O`) 更低，因此能提供更好的调试体验。
此外，类型为 `LOGICAL_ERROR` 的内部异常会立即导致程序崩溃，而不是以更平缓的方式失败。

```sh theme={null}
cmake -D CMAKE_BUILD_TYPE=Debug ..
```

<Note>
  如果你想使用 gdb 等调试器，请在上述命令中添加 `-D DEBUG_O_LEVEL="0"`，以移除所有编译器优化，因为这些优化可能会影响 gdb 查看或访问变量。
</Note>

运行 ninja 开始构建：

```sh theme={null}
ninja clickhouse
```

如果要构建所有二进制文件 (包括实用工具和测试) ，请直接运行不带参数的 ninja：

```sh theme={null}
ninja
```

您可以使用 `-j` 参数控制并行构建任务的数量：

```sh theme={null}
ninja -j 1 clickhouse
```

<Note>
  `clickhouse-server`、`clickhouse-client` 以及类似的二进制文件，在构建完成后都是 `programs/` 目录中指向 `clickhouse` 可执行文件的符号链接。

  :::tip
  CMake 为上述命令提供了简写方式：

  ```sh theme={null}
  cmake -S . -B build  # 配置构建，在仓库顶层目录中运行
  cmake --build build  # 编译
  ```
</Note>

<div id="running-the-clickhouse-executable">
  ## 运行 ClickHouse 可执行文件
</div>

构建成功后，可在 `ClickHouse/<build_dir>/programs/` 中找到该可执行文件：

ClickHouse 服务器会尝试在当前目录中查找配置文件 `config.xml`。
你也可以通过命令行参数 `-C` 指定配置文件。

要使用 `clickhouse-client` 连接到 ClickHouse 服务器，请打开另一个终端，进入 `ClickHouse/build/programs/`，然后运行 `./clickhouse client`。

如果你在 macOS 或 FreeBSD 上收到 `Connection refused` 消息，请尝试将主机地址指定为 127.0.0.1：

```bash theme={null}
clickhouse client --host 127.0.0.1
```

<div id="advanced-options">
  ## 高级选项
</div>

<div id="minimal-build">
  ### 最小构建
</div>

如果您不需要第三方库提供的功能，还可以进一步加快构建过程：

```sh theme={null}
cmake -DENABLE_LIBRARIES=OFF
```

如果出现问题，就只能你自己处理了……

Rust 需要联网。要禁用 Rust 支持：

```sh theme={null}
cmake -DENABLE_RUST=OFF
```

<div id="running-the-clickhouse-executable-1">
  ### 运行 ClickHouse 可执行文件
</div>

你可以用编译后的 ClickHouse 二进制文件替换系统中已安装的生产版 ClickHouse 二进制文件。
为此，请按照官网说明在你的机器上安装 ClickHouse。
接下来，运行：

```bash theme={null}
sudo service clickhouse-server stop
sudo cp ClickHouse/build/programs/clickhouse /usr/bin/
sudo service clickhouse-server start
```

请注意，`clickhouse-client`、`clickhouse-server` 等都是指向共用 `clickhouse` 可执行文件的符号链接。

你也可以使用系统中已安装的 ClickHouse 软件包里的配置文件来运行你自定义构建的 ClickHouse 可执行文件：

```bash theme={null}
sudo service clickhouse-server stop
sudo -u clickhouse ClickHouse/build/programs/clickhouse server --config-file /etc/clickhouse-server/config.xml
```

<div id="building-on-any-linux">
  ### 在任何 Linux 上构建
</div>

在 OpenSUSE Tumbleweed 上安装前置条件：

```bash theme={null}
sudo zypper install git cmake ninja clang-c++ python lld nasm yasm gawk
git clone --recursive https://github.com/ClickHouse/ClickHouse.git
mkdir build
cmake -S . -B build
cmake --build build
```

在 Fedora Rawhide 上安装前置条件：

```bash theme={null}
sudo yum update
sudo yum --nogpg install git cmake make clang python3 ccache lld nasm yasm gawk
git clone --recursive https://github.com/ClickHouse/ClickHouse.git
mkdir build
cmake -S . -B build
cmake --build build
```

<div id="building-in-docker">
  ### 在 Docker 中构建
</div>

你可以使用以下方式，在与 CI 类似的环境中于本地运行任意构建：

```bash theme={null}
python -m ci.praktika run "BUILD_JOB_NAME"
```

其中，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 外，无需任何额外依赖。