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

​
在 GitHub 上创建仓库

要开始为 ClickHouse 开发，您需要一个 GitHub 账户。 此外，请在本地生成一个 SSH 密钥 (如果您还没有) ，并将公钥上传到 GitHub，因为这是贡献补丁的前置条件。 接下来，点击右上角的 “fork” 按钮，在您的个人账户中 fork ClickHouse 仓库。 要贡献更改，例如修复某个问题或添加某项功能，请先将更改提交到您 fork 的某个分支，然后向主仓库发起包含这些更改的 “拉取请求”。 如需使用 Git 仓库，请先安装 Git。例如，在 Ubuntu 中，运行：
可在此处查看 Git 速查表。 更详细的 Git 手册见此处。

​
将代码仓库克隆到开发机

首先，将源文件下载到你的工作机器上，也就是克隆该代码仓库：
此命令会创建一个名为 ClickHouse/ 的目录，其中包含源代码、测试和其他文件。 你可以在 URL 后指定一个自定义检出目录，但务必确保该路径不包含空格，否则后续构建可能会失败。 ClickHouse 的 Git 仓库使用子模块来拉取第三方库。 默认情况下不会检出子模块。 你可以选择以下任一方式
  • 运行带有 --recurse-submodules 选项的 git clone，
  • 如果运行 git clone 时未使用 --recurse-submodules，请运行 git submodule update --init --jobs <N> 以显式检出所有子模块。 (例如，可将 <N> 设为 12 以并行下载。)
  • 如果运行 git clone 时未使用 --recurse-submodules，并且你希望使用 shallow 子模块检出以省略子模块中的历史记录、节省一些空间，请运行 ./contrib/update-submodules.sh。这种替代方案由 CI 使用，但不建议在本地开发中使用，因为它会让子模块的使用变得不那么方便，而且速度更慢。
要检查 Git 子模块的状态，请运行 git submodule status。 如果你收到以下错误信息
用于连接 GitHub 的 SSH 密钥不存在。 这些密钥通常位于 ~/.ssh。 要让 GitHub 接受 SSH 密钥，您需要在 GitHub 的设置中上传它们。 您也可以通过 HTTPS 克隆仓库：
不过，这样你将无法把更改推送到服务器。 你仍然可以暂时这样使用，之后再添加 SSH 密钥，并用 git remote 命令替换仓库的远程地址。 你也可以将原始 ClickHouse 仓库地址添加到本地仓库，以便从那里拉取更新：
成功运行此命令后，你就可以通过执行 git pull upstream master 从 ClickHouse 主仓库拉取更新。
请不要直接使用 git push，否则你可能会推送到错误的远程仓库和/或错误的分支。 最好显式指定远程仓库名和分支名，例如 git push origin my_branch_name。

​
编写代码

下面列出了一些快捷链接，在为 ClickHouse 编写代码时可能会用到：

​
IDE

Visual Studio Code 和 Neovim 都是过去开发 ClickHouse 时效果不错的选择。如果你使用 VS Code，我们建议使用 clangd extension 替代 IntelliSense，因为它的性能高得多。 CLion 也是一个很好的选择。不过，对于 ClickHouse 这样的大型项目，它可能会更慢一些。使用 CLion 时需要注意以下几点：
  • CLion 会自行创建一个 build 路径，并自动将构建类型设为 debug
  • 它使用的是 CLion 中指定的 CMake 版本，而不是你本地安装的版本
  • CLion 会使用 make 而不是 ninja 来运行构建任务 (这是正常行为)
你还可以使用其他 IDE，例如 Sublime Text、Qt Creator 或 Kate。

​
创建拉取请求

在 GitHub 的界面中进入你的 fork 仓库。 如果你是在某个分支上开发的，则需要选中该分支。 页面上会有一个“拉取请求”按钮。 其本质意思是：“创建一个请求，将我的更改合并到主仓库中”。 即使工作尚未完成，也可以创建拉取请求。 这种情况下，请在标题开头加上“WIP” (work in progress) ，后续可以再修改。 这有助于协作审查和讨论变更，也便于运行所有可用测试。 请务必简要说明你的更改，后续生成发布更新日志时会用到这段说明。 一旦 ClickHouse 员工给你的 PR 加上“can be tested”标签，测试就会开始。 前几项检查 (例如代码风格) 的结果会在几分钟内返回。 构建检查结果会在半小时内出来。 主要测试集会在一小时内给出结果。 系统会专门为你的拉取请求准备 ClickHouse 二进制构建产物。 要获取这些构建，请点击检查列表中“Builds”条目旁的“Details”链接。 在那里你会找到已构建的 ClickHouse .deb 包的直接链接，甚至可以将其部署到生产服务器上 (如果你不介意的话) 。

​
编写文档

凡是新增功能的拉取请求，都必须附带相应的文档。 如果你想预览文档改动，可在 这里 的 README.md 文件中查看如何在本地构建文档页面的说明。 向 ClickHouse 添加新函数时，可以参考下面的模板：

​
使用测试数据

开发 ClickHouse 时通常需要加载贴近真实场景的数据集。 这对于性能测试尤为重要。 我们专门准备了一组经过匿名化处理的网站分析数据。 还需要额外约 3GB 的可用磁盘空间。
在 clickhouse-client 中：
导入数据：
最后修改于 2026年7月2日