Repolode
提交项目
ktock

ktock/buildg

面向 Dockerfile 构建的交互式调试器，支持断点、单步执行和进入构建步骤的 Shell。

在 GitHub 查看
Star
1,503
Fork
40
未关闭 Issue
15
最近提交
3个月前

这是什么？

buildg 是一个针对 Dockerfile 构建过程的调试器。你无需反复重跑漫长的构建来猜测失败位置，而是可以在 Dockerfile 的指定行设置断点，逐条单步执行指令，并在每一步检查构建上下文和文件系统状态。

构建暂停在某一步时，可以打开该步骤状态下的交互式 Shell，运行自己的调试工具。也可以通过 --image 指定调试用镜像，让 Shell 使用构建镜像中不存在的工具。buildg 还通过 Debug Adapter Protocol（DAP）与编辑器集成，可在 VS Code、Emacs、Neovim 等编辑器中进行可视化断点调试。

buildg 基于 BuildKit 实现，其中包含尚未合并到上游的补丁，并支持 rootless 运行。目前原生执行仅支持 Linux，其他平台需要使用 Linux 虚拟机。项目仍处于早期阶段，也可作为 nerdctl 的子命令使用。

核心功能

  • 01可在 Dockerfile 指定行或失败的步骤上设置断点。
  • 02逐步执行构建指令，并可继续运行到指定断点。
  • 03在构建步骤中打开交互式 Shell 检查其状态。
  • 04可挂载自定义调试镜像，使用自己的工具。
  • 05通过 DAP 与 VS Code、Emacs、Neovim 等编辑器集成。
  • 06支持 rootless 运行。

适用场景

  • 定位大型、耗时较长的 Dockerfile 中导致构建失败的指令。
  • 检查中间构建步骤的文件和环境变量。
  • 在 VS Code 或 Neovim 中调试 Dockerfile 构建。
  • 通过检查远程缓存的构建，排查构建缓存问题。

快速上手

  1. 1

    安装 Go 1.23+ 并克隆仓库

    git clone https://github.com/ktock/buildg
  2. 2

    使用 make 构建二进制文件

    make
  3. 3

    将二进制文件安装到系统中

    sudo make install
  4. 4

    对构建上下文启动调试会话

    buildg debug /path/to/build/context

使用前须知

  • 原生运行仅支持 Linux；其他平台需要使用 Linux 虚拟机。
  • 该项目处于早期阶段，基于带有未合并补丁的 BuildKit 构建。
  • 与 IDE（DAP）集成需要使用 rootless 模式运行。

标签

#docker#dockerfile#debugger#buildkit#container#devtools#dap

常见问题

buildg 是什么？
面向 Dockerfile 构建的交互式调试器，支持断点、单步执行和进入构建步骤的 Shell。 buildg 是一个针对 Dockerfile 构建过程的调试器。你无需反复重跑漫长的构建来猜测失败位置，而是可以在 Dockerfile 的指定行设置断点，逐条单步执行指令，并在每一步检查构建上下文和文件系统状态。
buildg 可以免费使用吗？用的什么许可证？
buildg 以 Apache-2.0 许可证开源。用于商业产品前，请先确认许可证条款。
buildg 还在维护吗？
半年内有更新。buildg 最近一次提交是在 2026年7月30日。
buildg 适合用来做什么？
定位大型、耗时较长的 Dockerfile 中导致构建失败的指令。 检查中间构建步骤的文件和环境变量。 在 VS Code 或 Neovim 中调试 Dockerfile 构建。 通过检查远程缓存的构建，排查构建缓存问题。
buildg 怎么安装和运行？
安装 Go 1.23+ 并克隆仓库: git clone https://github.com/ktock/buildg 使用 make 构建二进制文件: make 将二进制文件安装到系统中: sudo make install 对构建上下文启动调试会话: buildg debug /path/to/build/context
在哪里获取 buildg？
源代码和安装说明在 GitHub 上：https://github.com/ktock/buildg

概要由 AI 根据项目 README 生成；GitHub 数据每日更新。

相关项目