在正式启动 CodeBuddy 接口调试之前，有一项前提工作必不可少：Node.js 环境必须稳定支持 CLI 运行。简单来说，如果系统无法识别 codebuddy 命令，后续所有调试操作都将停留在第一步。因此，提前将环境配置妥当，后续流程才能顺畅无阻。

环境配置的要求非常明确：Node.js 版本需 ≥ v18.20，npm 版本需 ≥ v8.0。然而，常见的陷阱并非版本本身，而是 PATH 环境变量未生效，或者全局 bin 目录缺乏写入权限。接下来，我们按步骤逐一排查并解决这些问题。

验证 Node.js 与 npm 是否已正确安装

打开终端（Windows 用户建议使用 PowerShell，避免使用古老的 CMD），直接执行以下命令：

node --version && npm --version

输出必须同时显示两个版本号。如果其中任意一条返回“command not found”，说明环境变量尚未生效——这几乎是 90% 调试失败的首要原因。

这里有一个容易被忽略的细节：Windows 用户在安装 Node.js 时，必须勾选“Add to PATH”选项，安装完成后还需关闭所有旧终端窗口，再重新打开一个新的。旧窗口中的 PATH 信息不会自动刷新，切勿被其误导。

解决 PATH 环境变量未生效的问题

方法一：Windows 快速重载（推荐）

右键“开始”→选择“Windows PowerShell（管理员）”→粘贴并执行以下代码：[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:Program Filesnodejs", "Machine")→然后重启 PowerShell。操作完成后，PATH 便已更新完毕。

方法二：macOS/Linux 手动追加

编辑 ~/.zshrc 或 ~/.bash_profile，在末尾添加一行：export PATH="/usr/local/bin:$PATH"→保存后执行 source ~/.zshrc 使其立即生效。

修复完成后，务必在新的终端窗口中再次运行 node -v，确认版本号正常显示才算真正解决。这一步不可省略。

检查全局 bin 目录的写入权限

版本验证通过仅是第一步，还需要确保 npm 能够将全局包安装至正确的位置。

首先确认 npm 的全局路径：执行 npm config get prefix。典型输出：macOS/Linux 为 /usr/local，Windows 为 C:Users\你的用户名\AppData\Roaming\npm。

接着测试写入能力：运行 npm install -g dummy-package-test。如果出现 EACCES 错误，说明当前用户缺少写入权限——此时切勿使用 sudo 强制执行，否则会打乱后续 CLI 的权限模型，带来更多隐患。

更安全的做法是更改 npm 的默认全局目录：

① 创建新目录：mkdir ~/.npm-global
② 配置 npm 使用该新目录：npm config set prefix ~/.npm-global
③ 将该目录添加到 PATH 中：export PATH=~/.npm-global/bin:$PATH（记得写入 shell 配置文件并执行 source 使其永久生效）

这样一来，权限问题便得到彻底规避，后续安装任何全局包都不会再遇到权限困扰。