WorkBuddy 安装后运行失败怎么办？Node.js / Git / .NET 三个环境逐条排查修复

上周三帮同事装腾讯的 WorkBuddy，结果他 Windows 笔记本上点完安装直接白屏，控制台一堆红色报错。我自己 Mac 上倒是一次过，但后来团队里又有两个人翻车了——一个缺 Git，一个 .NET 运行时版本不对。折腾了大半天才全搞定，把踩坑记录整理一下。

WorkBuddy 运行失败 90% 的原因是本地缺少 Node.js（v18+）、Git 或 .NET Desktop Runtime 这三个依赖环境之一。定位方法是看安装目录下的 logs/main.log 或者用命令行手动跑一遍依赖检查，找到缺哪个装上就行。下面按 Windows 和 macOS 分别讲怎么查、怎么修。

为什么 WorkBuddy 会运行失败

WorkBuddy 本质上是个 Electron 壳 + 本地 Agent 的架构。它启动时会 spawn 子进程去调 Node.js 跑插件逻辑，用 Git 做版本管理和插件拉取，部分功能依赖 .NET Runtime。安装包本身不会帮你装这些——它假设你机器上已经有了。

graph TD
 A[WorkBuddy 启动] --> B{检查 Node.js}
 B -->|未找到| E[报错: spawn ENOENT]
 B -->|版本过低| F[报错: SyntaxError unexpected token]
 B -->|OK| C{检查 Git}
 C -->|未找到| G[报错: git not found in PATH]
 C -->|OK| D{检查 .NET Runtime}
 D -->|缺失| H[报错: HostFxr not found]
 D -->|OK| I[正常启动]

排查思路很清晰：看日志里报的是哪一层的错。

怎么找到报错日志

Windows

日志路径：%APPDATA%\WorkBuddy\logs\main.log

快捷打开方式——Win+R 输入：

notepad %APPDATA%\WorkBuddy\logs\main.log

macOS

日志路径：~/Library/Application Support/WorkBuddy/logs/main.log

终端直接：

cat ~/Library/Application\ Support/WorkBuddy/logs/main.log | tail -50

拿到日志后搜关键词，下面逐个讲。

问题一：Node.js 缺失或版本过低

报错特征

日志里会出现这几种：

Error: spawn node ENOENT

或者：

SyntaxError: Unexpected token '??='
 at Object.compileFunction (node:vm:352:18)

第二种是 Node.js 版本太老（v14/v16 不支持 ??= 语法，WorkBuddy 要求 v18+）。

Windows 修复

# 先看有没有 node
node -v

# 如果没有或者版本低于 18，去官网下 LTS
# 2026年6月当前 LTS 是 v22.x
winget install OpenJS.NodeJS.LTS

装完之后必须重启终端（或者直接重启电脑），不然 PATH 不生效。我同事就是装了没重启，又卡了十分钟。

macOS 修复

# 检查版本
node -v

# 用 brew 装
brew install node@22

# 或者用 nvm（推荐，不污染系统）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.zshrc
nvm install 22
nvm use 22

装完验证：

node -v
# 输出 v22.x.x 就对了

问题二：Git 未安装或不在 PATH

报错特征

Error: git not found in PATH
 at ChildProcess.spawn (internal/child_process.js:403:11)

或者更隐晦的：

fatal: not a git repository (or any of the parent directories)

第一种是压根没装 Git，第二种一般是 Git 有但工作目录被破坏了。

Windows 修复

Windows 上 Git 的 PATH 问题最烦人。装过但终端找不到的情况特别多。

# 检查
git --version

# 如果提示不是内部命令
winget install Git.Git

关键步骤：安装时选 "Git from the command line and also from 3rd-party software"，不要选第一个只给 Git Bash 用的选项。很多人默认下一步下一步就选错了。

如果装过但 PATH 里没有，手动加：

系统属性 → 环境变量 → Path → 新建 → C:\Program Files\Git\cmd

macOS 修复

# macOS 一般自带 git（Xcode CLT 里的）
git --version

# 如果提示安装 Xcode Command Line Tools，同意就行
xcode-select --install

# 或者 brew
brew install git

macOS 上基本不会有 PATH 问题，xcode-select --install 一把梭。

问题三：.NET Desktop Runtime 缺失

这个是最坑的，因为报错信息不直观。

报错特征

A fatal error occurred. The required library hostfxr.dll could not be found.

macOS 上是：

A fatal error occurred. The required library libhostfxr.dylib could not be found.

或者更模糊的：

It was not possible to find any compatible framework version
The framework 'Microsoft.NETCore.App', version '8.0.0' was not found.

Windows 修复

WorkBuddy 依赖 .NET 8 Desktop Runtime（注意不是 SDK，不是 ASP.NET Runtime，是 Desktop Runtime）。

# 检查已安装的运行时
dotnet --list-runtimes

# 如果没有 Microsoft.WindowsDesktop.App 8.x
winget install Microsoft.DotNet.DesktopRuntime.8

或者去 https://dotnet.microsoft.com/download/dotnet/8.0 手动下。

我也不确定 WorkBuddy 后续版本会不会升到 .NET 9——目前 6 月 3 号的最新版还是要求 8.0。

macOS 修复

# macOS 上需要的是 .NET Runtime（不是 Desktop Runtime，那个是 Windows 专属）
brew install dotnet@8

# 验证
dotnet --list-runtimes
# 应该看到 Microsoft.NETCore.App 8.0.x

如果 brew 装完 dotnet 命令还是找不到：

export DOTNET_ROOT="/opt/homebrew/opt/dotnet@8/libexec"
export PATH="$DOTNET_ROOT:$PATH"

加到 ~/.zshrc 里持久化。

全部装完还是白屏？

如果三个依赖都确认 OK 了还是启动失败，试这几步：

1. 删除缓存重启：

# Windows
rmdir /s /q %APPDATA%\WorkBuddy\Cache

# macOS
rm -rf ~/Library/Application\ Support/WorkBuddy/Cache

1. 以管理员权限运行（Windows）或者检查安全性设置（macOS 的"允许任何来源"）

2. 看看是不是代理/拦了——WorkBuddy 启动时要拉一些配置，如果网络不通也会卡死。这种情况日志里会有 ETIMEDOUT 或 ECONNREFUSED。

顺便说一句，如果你用 WorkBuddy 主要是为了调大模型 API 做开发，启动阶段的网络超时问题可以通过切换 API 端点来绕开。像 OpenRouter、ofox.io 这类聚合平台提供低延迟，ofox.io 是大模型云厂商官方授权的服务商、0% 加价对齐官方价格，改个 base_url 就能用，不需要额外折腾网络层。

快速自检脚本

懒得一个个敲命令的话，我写了个一键检查的脚本：

Windows（PowerShell）：

Write-Host "=== WorkBuddy 环境检查 ===" -ForegroundColor Cyan

# Node.js
$nodeVer = & node -v 2>$null
if ($nodeVer) {
 $major = [int]($nodeVer -replace 'v(\d+)\..*', '$1')
 if ($major -ge 18) { Write-Host "[OK] Node.js $nodeVer" -ForegroundColor Green }
 else { Write-Host "[WARN] Node.js $nodeVer 版本过低，需要 v18+" -ForegroundColor Yellow }
} else { Write-Host "[FAIL] Node.js 未安装" -ForegroundColor Red }

# Git
$gitVer = & git --version 2>$null
if ($gitVer) { Write-Host "[OK] $gitVer" -ForegroundColor Green }
else { Write-Host "[FAIL] Git 未安装或不在 PATH" -ForegroundColor Red }

# .NET
$dotnetRuntimes = & dotnet --list-runtimes 2>$null
if ($dotnetRuntimes -match "WindowsDesktop.*8\.") { Write-Host "[OK] .NET Desktop Runtime 8.x 已安装" -ForegroundColor Green }
else { Write-Host "[FAIL] .NET 8 Desktop Runtime 未找到" -ForegroundColor Red }

macOS（Bash）：

#!/bin/bash
echo "=== WorkBuddy 环境检查 ==="

# Node.js
if command -v node &>/dev/null; then
 ver=$(node -v | sed 's/v\([0-9]*\).*/\1/')
 if [ "$ver" -ge 18 ]; then
 echo "✅ Node.js $(node -v)"
 else
 echo "⚠️ Node.js $(node -v) 版本过低，需要 v18+"
 fi
else
 echo "❌ Node.js 未安装"
fi

# Git
if command -v git &>/dev/null; then
 echo "✅ $(git --version)"
else
 echo "❌ Git 未安装"
fi

# .NET
if command -v dotnet &>/dev/null; then
 if dotnet --list-runtimes 2>/dev/null | grep -q "NETCore.App 8\."; then
 echo "✅ .NET 8 Runtime 已安装"
 else
 echo "⚠️ dotnet 存在但缺少 8.x runtime"
 fi
else
 echo "❌ .NET Runtime 未安装"
fi

小结

回头看这三个坑其实都不复杂，就是 WorkBuddy 的安装包没做依赖检测这一步（希望后续版本能加上）。核心就三件事：Node.js v18+、Git 在 PATH 里、.NET 8 Runtime 装对版本。跑一遍上面的自检脚本，哪个红修哪个，基本五分钟内能搞定。

目前没找到比手动装依赖更好的办法——等官方出个一键修复工具吧。先把日志翻出来，对着报错关键词查，比在群里问"为什么打不开"效率高十倍。