AI 编程伙伴 - 从零开始安装 CodeBuddy Code

在 AI 辅助编程成为主流的今天，腾讯云推出的 CodeBuddy Code 是一款基于腾讯云 AI 技术的智能编程工具，能用自然语言驱动整个开发流程——从代码编写、测试、调试到部署，一站式搞定。

本文将从环境准备到安装验证，手把手完成 CodeBuddy Code 的安装，并针对常见问题给出解决方案。

一、安装前的环境准备

1.1 检查 Node.js 版本

CodeBuddy Code 要求 Node.js 18.20 或更高版本。先检查当前的版本：

node --version

如果输出低于 v18.20，需要先升级 Node.js。

1.2 升级 Node.js（以 Ubuntu/Debian 为例）

如果使用的是 Ubuntu/Debian 系统，且系统自带的老版本 Node.js，推荐通过 NodeSource 源升级：

# 添加 NodeSource LTS 源curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -# 安装新版 Node.jssudo apt install -y nodejs

踩坑提醒： 如果升级时遇到 dpkg: error processing archive 报错，提示与 libnode-dev 包冲突，是因为旧版 libnode-dev 占用了部分文件路径。解决方法：

# 先卸载冲突的 libnode-devsudo apt remove --purge libnode-dev# 清理缓存sudo apt clean# 重新安装 Node.jssudo apt install nodejs# 清理旧依赖（可选）sudo apt autoremove

安装完成后验证：

node --version# 应输出 v18.x.x 或更高

二、安装 CodeBuddy Code

CodeBuddy Code 提供了两种安装方式：包管理器安装 和 原生二进制安装。

方式一：包管理器安装（推荐新手使用）

支持 npm、pnpm、yarn、bun 四种包管理器，选择习惯的即可：

# npmnpm install -g @tencent-ai/codebuddy-code# pnpmpnpm add -g @tencent-ai/codebuddy-code# yarnyarn global add @tencent-ai/codebuddy-code# bunbun install -g @tencent-ai/codebuddy-code

踩坑提醒： 如果安装时报 EACCES: permission denied 错误，说明 npm 全局安装目录没有写权限。不要用 sudo 安装，推荐修改 npm 全局路径：

# 创建自定义全局目录mkdir -p ~/.npm-global# 设置 npm 全局安装路径npm config set prefix ~/.npm-global# 将路径加入环境变量echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrcsource ~/.bashrc# 重新安装npm install -g @tencent-ai/codebuddy-code

macOS 用户还可以用 Homebrew 安装（无需 Node.js）：

# 添加 tap 源brew tap Tencent-CodeBuddy/tap# 安装brew install codebuddy-code

方式二：原生二进制安装（Beta）

原生二进制版本的最大优势：无需 Node.js，单一可执行文件，安装更快。

macOS / Linux：

curl -fsSL https://www.codebuddy.cn/cli/install.sh | bash

Windows（PowerShell）：

irm https://www.codebuddy.cn/cli/install.ps1 | iex

如果已经通过 npm 安装过，可以一键迁移到原生版本：

codebuddy install

验证安装

无论哪种方式，安装完成后都需要验证：

codebuddy --version

看到版本号输出，说明安装成功！

三、首次登录

安装成功后，首次启动会提示选择登录方式：

Select login method:› Log in via Chinese Site        # 国内用户推荐  Log in via International Site   # 海外用户  Log in via Enterprise Domain    # 企业专享版/私有化部署  Log in via iOA (Tencent only)  # 腾讯内部员工

登录方式	适用场景	说明
Chinese Site	国内用户	通过腾讯云国内站认证，支持国内主流模型
International Site	海外用户	通过腾讯云国际站认证，支持海外主流模型
Enterprise Domain	企业专享版	连接企业自建服务，需输入服务地址
iOA	腾讯员工	腾讯内部零信任认证

使用方向键选择，按回车确认后会自动打开浏览器完成认证。

四、快速上手

4.1 启动交互模式

cd /path/to/your/projectcodebuddy

4.2 初始化项目上下文（强烈推荐）

首次进入项目时，建议先运行：

> /init

这会预先构建项目知识图谱，让 AI 更准确理解代码结构，同时减少后续对话的 Token 消耗。

4.3 开始对话

> 帮我分析这个项目的结构> 这段代码有什么潜在的性能问题？> 为这个 API 接口写单元测试

4.4 单次命令模式

适合脚本化和自动化场景：

# 直接提问codebuddy -p "优化这个 SQL 查询的性能"# 管道输入cat error.log | codebuddy -p "分析这些错误日志"# 需要文件操作权限时加 -ycodebuddy -p "审查 src/utils.js 的代码质量" -y

五、IDE 集成

CodeBuddy Code 也支持与主流 IDE 深度集成：

VS Code / Cursor / JetBrains：通过插件市场安装 CodeBuddy 插件，使用 codebuddy --ide 启动即可自动连接
Zed 编辑器：通过 ACP 协议集成，使用 codebuddy --acp 启动

IDE 集成后可以享受文件预览、差异对比、诊断信息等增强功能。

六、更新与卸载

更新

CodeBuddy Code 默认自动更新。如需手动更新：

codebuddy update

或通过包管理器重新安装：

npm install -g @tencent-ai/codebuddy-code

卸载

# npmnpm uninstall -g @tencent-ai/codebuddy-code# Homebrewbrew uninstall codebuddy-code# 原生二进制rm -f ~/.local/bin/codebuddy

如需彻底清理配置文件：

rm -rf ~/.codebuddyrm -rf ~/.local/share/codebuddy

七、常见问题汇总

问题	原因	解决方案
`codebuddy: command not found`	PATH 中没有安装路径	将 `~/.npm-global/bin` 加入 PATH，或原生安装路径 `~/.local/bin` 加入 PATH
`EACCES: permission denied`	npm 全局目录无写权限	修改 npm prefix 为 `~/.npm-global`（见上文）
`dpkg: error processing archive`	旧版 libnode-dev 冲突	先卸载 `libnode-dev`，再安装新版 Node.js
网络连接失败	网络或镜像源问题	配置镜像源：`npm config set registry https://registry.npmmirror.com`
原生安装后命令不可用	环境变量未生效	将 `~/.local/bin` 加入 PATH，或重启终端

八、获取帮助

提交问题：https://cnb.cool/codebuddy/codebuddy-code/-/issues
技术支持邮箱：codebuddy@tencent.com
官方网站：https://copilot.tencent.com/cli
CLI：https://www.codebuddy.ai/docs/zh/cli/common-workflows

CodeBuddy Code 安装只需几步，却能显著提升开发效率。用自然语言描述需求，让 AI 成为工作编程伙伴！