CodeGraph 第 2 课：安装与配置

一、系统要求

CodeGraph 对系统环境的要求非常宽松，不需要预先安装 Node.js，因为它在 0.9 版本后捆绑了自己的 Node 运行时。

⚠️ 如果你选择通过 npm 安装，则需要 Node.js ≥ 20.0.0。但官方推荐的安装方式无需 Node.js。

二、安装 CLI

方式一：官方安装器（推荐，无需 Node.js）

macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

Windows (PowerShell)：

irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

安装器会自动将 codegraph 添加到 PATH。安装完成后，需要打开一个新的终端才能使用 codegraph 命令。

方式二：通过 npm 安装

如果你已有 Node.js 环境（≥ 20.0.0），也可以使用 npm：

npm i -g @colbymchenry/codegraph

方式三：零安装运行（临时使用）

不安装到系统，直接通过 npx 运行：

npx @colbymchenry/codegraph

升级

任何时候运行以下命令即可升级到最新版本：

codegraph upgrade

三、配置 MCP 服务器（连接 AI 编程助手）

安装 CLI 后，还需要运行 codegraph install 来将 CodeGraph 连接到你的 AI 编程助手。

codegraph install

这个命令会自动检测并配置你电脑上已安装的 AI 编程工具，包括：

• Claude Code

• Cursor

• Codex CLI

• opencode

• Hermes Agent

• Gemini CLI

• Antigravity IDE

• Kiro

💡 codegraph install 只负责连接 AI 助手，不会索引任何代码。索引项目是下一步的独立操作。

配置完成后，重启你的 AI 编程助手（如 Claude Code、Cursor），让 MCP 服务器重新加载。

手动配置 MCP（可选）

如果你需要手动配置，可以在 MCP 客户端配置文件中添加以下内容（如 ~/.claude.json）：

{
  "mcpServers": {
    "codegraph": {
      "command": "/path/to/codegraph-server",
      "args": ["--mcp"]
    }
  }
}

服务器会自动索引当前工作目录。

四、初始化项目（构建知识图谱）

进入你的项目目录，运行：

cd your-project
codegraph init

这个命令会一步完成两件事：

1. 在项目根目录创建 .codegraph/ 文件夹

2. 构建完整的代码知识图谱

多项目 / Monorepo 场景

如果你的项目是 monorepo 结构，建议在每个子项目根目录分别初始化：

codegraph init /path/to/frontend
codegraph init /path/to/backend
codegraph init /path/to/shared-lib

五、自动同步（无需手动更新）

自动同步默认开启。CodeGraph 会监听项目文件变化，在你保存代码后自动增量更新图谱——无需手动重新运行任何命令。

六、常见问题与故障排除

❌ 问题 1：codegraph: command not found

原因：安装器已将 codegraph 添加到 PATH，但当前 shell 未刷新。

解决：打开一个新的终端窗口，或运行 source ~/.zshrc / source ~/.bashrc。

❌ 问题 2：安装器跳过安装，提示已存在

原因：旧版本安装器的一个已知 bug，会在 npx 上下文中误判。

解决：直接通过 npm 全局安装：

npm install -g @colbymchenry/codegraph

❌ 问题 3：Tool execution failed: CodeGraph not initialized

原因：当前项目尚未运行 codegraph init。

解决：在项目根目录运行 codegraph init。

❌ 问题 4：database is locked

原因：数据库锁文件残留。

解决：删除项目中的 .codegraph/ 目录，然后重新运行 codegraph init。

❌ 问题 5：MCP server 未连接

解决步骤：

1. 确认项目已初始化（已运行 codegraph init）

2. 检查 MCP 配置文件中的路径是否正确

3. 在终端手动测试：codegraph serve --mcp

4. 重启 AI 编程助手

七、卸载

仅移除 AI 助手配置（保留 CLI）

codegraph uninstall --keep-cli

完全卸载（移除 CLI + 所有配置）

codegraph uninstall

移除单个项目的索引

codegraph uninit

八、安装流程速查表