Windows + WSL2 上的 Beadbox

如果你的项目位于 WSL2 中——任何位于 \\wsl.localhost\ 或 \\wsl$\ 下的路径——请在 WSL 中安装 Linux 版 Beadbox，并通过 WSLg 启动。原生的 Windows .exe 不支持 WSL2 路径。本指南面向 Ubuntu 24.04 LTS；不支持 22.04（详见 Prerequisites）。

为什么要在 WSL 中使用 Linux 版 Beadbox

当你的工作区路径形如 \\wsl.localhost\Ubuntu\home\you\my-project 时，运行在 Windows 上的 Beadbox.exe 每次调用 bd CLI 都必须穿越 9P 文件系统桥。bd CLI 每次调用都会启动 Go 运行时并重新初始化嵌入式 Dolt 存储，而 WSL2 中的 Linux 内核所强制执行的 flock() 语义在 Windows 一侧无法可靠遵守。

结果是两种失败模式：热调用耗时约 1240 ms（远超 Beadbox 500 ms 的轮询窗口），以及当两个进程同时访问工作区时间歇性出现的 flock 错误。更干净的解法是让 Beadbox 运行在工作区所在的位置——也就是 WSL2 内部——再让 WSLg 把 GUI 渲染到 Windows 上。

前置条件

本指南面向 WSL2 中的 Ubuntu 24.04 LTS。Ubuntu 22.04 无法工作——Beadbox 的 .deb 依赖 libwebkit2gtk-4.1，该库仅在 24.04 及更高版本中原生提供。较旧的 WSL2 发行版会在安装步骤报未满足依赖错误。

在执行步骤 1 之前，需要满足两项前置条件：

  1. 默认使用 WSL2，而不是 WSL1。WSLg 只在 WSL2 上渲染 GUI 应用。安装发行版之前，先在 PowerShell 中运行一次：

    wsl --set-default-version 2

  2. 安装 Ubuntu 24.04（或升级现有发行版）。该步骤是交互式的——镜像下载需要几分钟，下载完成后会提示你创建 Linux 用户名和密码：

    wsl --install Ubuntu-24.04

  3. 确认该发行版运行在 WSL2 上：

    wsl --list --verbose

输出中 Ubuntu-24.04 旁边应显示 VERSION 2。如果显示 1，请转换：wsl --set-version Ubuntu-24.04 2。

在 WSL2 中安装 Linux 版 Beadbox

以下命令在你的 Ubuntu 24.04 WSL2 终端中运行。在 PowerShell 中执行 wsl -d Ubuntu-24.04 打开终端，或者从 Windows Terminal 的下拉菜单中选择该发行版。

1. 安装 beads CLI

Beadbox 封装了 bd CLI，因此两者都需要。先安装 bd：

curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

用 bd --version 验证。你应该看到 bd 的版本号字符串。

2. 下载 Beadbox 的 .deb

从 GitHub releases 获取最新的 Linux .deb：

VER=$(curl -sSL https://api.github.com/repos/beadbox/beadbox/releases/latest | sed -n 's/.*"tag_name":[[:space:]]*"v\{0,1\}\([^"]*\)".*/\1/p')
curl -L -o beadbox.deb "https://github.com/beadbox/beadbox/releases/download/v${VER}/beadbox_${VER}_Linux_amd64.deb"

3. 安装 .deb

先刷新 apt 索引——全新的 WSL2 发行版自带的软件包列表是过期的，否则安装时会因传递依赖出现 404 而失败。然后在同一行中安装 .deb：

sudo apt-get update && sudo apt install ./beadbox.deb

如果在刷新之后 apt 仍报告缺少依赖，运行 sudo apt --fix-broken install 后重试。

通过 WSLg 启动

WSLg 随 Windows 10 和 11 上的 WSL2 一同提供，可以直接将 Linux GUI 应用渲染到你的 Windows 桌面。无需配置 X server，无需额外设置——直接运行应用即可：

beadbox

首次启动时，WSLg 协商显示连接可能需要几秒。之后，Beadbox 表现得和任何原生窗口一样：你可以把它固定到任务栏、用 alt-tab 切换、跨显示器拖动。打开工作区时，请指向 Linux 一侧的路径（~/my-project），而不是 Windows 一侧的路径。在 WSL 内部，~/ 才是正确的家目录。

提示：如果你想要一个开始菜单的快捷方式，.deb 安装时会注册一个 .desktop 项，Windows 会自动将它显示为 "Beadbox (Ubuntu)" 之类。安装后在开始菜单中搜索即可找到。

已经遇到 flock 错误？

如果你装了 Beadbox.exe 并尝试打开 WSL 工作区，很可能看到了提及 flock、嵌入模式失败或工作区无法加载的错误。修复方法很直接：

  1. 在 Beadbox.exe 中关闭该工作区（或干脆退出应用）。原生 Windows 构建无法处理这个工作区。
  2. 按上面的安装步骤，在你的 WSL2 发行版中安装 Linux 版 Beadbox。
  3. 在 WSL 内部启动 Beadbox（在 WSL 终端运行 beadbox），并使用 Linux 路径（~/my-project）打开工作区。

你可以保留 Beadbox.exe 用于托管在 Windows 一侧的项目（路径形如 C:\Users\you\my-project）。Windows 构建对那些项目没有问题——只有托管在 WSL 中的项目才需要 Linux 构建。

故障排查

启动时出现 libEGL / Mesa 警告

首次运行 beadbox 时，终端可能会打印来自 libEGL、Mesa 或 GL 驱动的警告，提示缺少硬件加速或回退到软件渲染。这在 WSLg 下属于正常现象——WSL2 不会把你的 Windows GPU 直接暴露给 Linux 一侧，因此 GUI 栈会回退到软件路径。应用可以正常启动，并以 Beadbox 的全速运行；这些警告只是噪声，不是错误。

背景与参考资料

两种构建（Windows .exe 和 Linux .deb）来自同一份 Beadbox 代码。.exe 无法驱动 WSL 工作区是结构性原因，并非我们计划修复的 bug——延迟的数学和文件系统桥都不利于这条路径。

如果你想了解这个决定背后的架构细节，下方链接列出了相关的设计文档以及排除被否决方案所用的延迟追踪数据。