先决条件

ClickHouse 可以在 Linux、FreeBSD 和 macOS 上构建。 如果你使用 Windows，你仍然可以在运行 Linux 的虚拟机中构建 ClickHouse，例如 使用 VirtualBox 的 Ubuntu。

在 GitHub 上创建一个仓库

要开始为 ClickHouse 开发，你需要一个 GitHub 账户。 请在本地生成一个 SSH 密钥（如果你还没有的话），并将公钥上传到 GitHub，因为这对于贡献补丁是一个前提。

接下来，在你的个人账户中通过点击右上角的“fork”按钮来分叉 ClickHouse 仓库。

要提交更改，例如修复问题或添加功能，首先将更改提交到你分叉的一个分支中，然后创建一个与主仓库的“Pull Request”。

要使用 Git 仓库，请安装 Git。例如，在 Ubuntu 中运行：

你可以在 这里 找到 Git 速查表。 详细的 Git 手册在 这里。

将仓库克隆到你的开发机器

首先，将源文件下载到你的工作机器，也就是克隆仓库：

此命令创建一个名为 ClickHouse/ 的目录，其中包含源代码、测试和其他文件。 你可以在 URL 后指定一个自定义目录用于检出，但重要的是此路径不能包含空格，因为这可能会在后续构建中出错。

ClickHouse 的 Git 仓库使用子模块来引入第三方库。 默认情况下，子模块不会被检出。 你可以选择

• 运行 git clone，并带上 --recurse-submodules 选项，

• 如果 git clone 在没有 --recurse-submodules 的情况下运行，运行 git submodule update --init --jobs <N> 来显式检出所有子模块。 (<N> 可以设置为，例如 12，以并行下载。)

• 如果 git clone 在没有 --recurse-submodules 的情况下运行，并且你希望使用 稀疏 和 浅层 子模块检出，以省略不需要的文件和历史记录以节省空间（大约 5 GB 而不是大约 15 GB），运行 ./contrib/update-submodules.sh。此替代方案由 CI 使用，但不建议用于本地开发，因为它使得使用子模块变得更不方便且更慢。

要检查 Git 子模块的状态，运行 git submodule status。

如果你收到以下错误信息

则表示缺少用于连接到 GitHub 的 SSH 密钥。 这些密钥通常位于 ~/.ssh。 为了让 SSH 密钥被接受，你需要在 GitHub 的设置中上传它们。

你也可以通过 HTTPS 克隆仓库：

然而，这样你将无法向服务器发送你的更改。 你仍然可以暂时使用它，稍后添加 SSH 密钥，并使用 git remote 命令替换仓库的远程地址。

你也可以将原始 ClickHouse 仓库地址添加到你的本地仓库，以从那里拉取更新：

成功运行此命令后，你将能够通过运行 git pull upstream master 从主 ClickHouse 仓库拉取更新。

提示

请勿直接使用 git push，你可能会推送到错误的远程和/或错误的分支。 最好明确指定远程和分支名称，例如 git push origin my_branch_name。

编写代码

以下是一些在为 ClickHouse 编写代码时可能有用的快速链接：

• ClickHouse 架构。
• 代码风格指南。
• 第三方库
• 编写测试
• 开放问题

IDE

Visual Studio Code 和 Neovim 是过去开发 ClickHouse 时非常适用的两个选项。如果你在使用 VS Code，我们建议使用 clangd 扩展 来替代 IntelliSense，因为它性能更佳。

CLion 是另一个很好的替代品。然而，在像 ClickHouse 这样的大型项目上可能会比较慢。使用 CLion 时需要注意几件事：

• CLion 会自行创建一个 build 路径，并自动选择 debug 作为构建类型
• 它使用的 CMake 版本是在 CLion 中定义的，而不是你安装的版本
• CLion 将使用 make 来运行构建任务，而不是 ninja（这是正常行为）

你还可以使用其他 IDE，例如 Sublime Text、Qt Creator 或 Kate。

创建 Pull Request

在 GitHub 的 UI 中导航到你的分叉仓库。 如果你在一个分支中进行开发，你需要选择该分支。 界面上将会有一个“Pull request”按钮。 本质上，这意味着“创建一个请求以接受我的更改到主仓库”。

即使工作尚未完成，也可以创建一个 Pull Request。 在这种情况下，请在标题的开头加上“WIP”（进行中的工作），待后续修改。 这对于协作审核和讨论更改以及运行所有可用测试来说非常有用。 重要的是你要提供一个对你所做更改的简要描述，以后用于生成发布变更日志。

一旦 ClickHouse 员工为你的 PR 添加了“可以测试”的标签，测试将立即开始。 一些初步检查（例如代码风格）的结果将在几分钟内返回。 构建检查结果将在半小时内返回。 主要的测试结果将在一小时内报告。

系统将会为你的 Pull Request 单独准备 ClickHouse 二进制构建。 要检索这些构建，单击在检查列表中“构建”条目旁的“详细信息”链接。 在那里你将找到构建的 ClickHouse .deb 包的直接链接，你可以在生产服务器上进行部署（如果你不怕的话）。

编写文档

每个添加新功能的 Pull Request 必须附带适当的文档。 如果你想预览文档的更改，README.md 文件中提供了如何在本地构建文档页面的说明 这里。 在 ClickHouse 中添加新功能时，可以使用以下模板作为指南：

使用测试数据

开发 ClickHouse 通常需要加载真实的 数据集。 这对性能测试尤其重要。 我们准备了一套经过匿名化处理的网页分析数据。 它额外需要大约 3GB 的可用磁盘空间。

在 clickhouse-client 中：

导入数据：