GitNexus 完全教程：全局安装与多项目无缝调用

📚 教程概述

本教程将详细讲解如何一次配置，全局使用 GitNexus，让你在多个项目中都能享受 AI 深度理解代码的能力，告别“为每个项目单独配置”的繁琐。

适用读者：已经受够了“改好一个 BUG 又出现新的”、希望 AI 真正理解项目架构的开发者。

第1章：GitNexus 是什么？为什么需要全局调用？

1.1 核心价值

GitNexus 是一个为 AI 编程助手打造的代码知识图谱工具。它会把你的整个代码库“嚼碎”，梳理出每一个依赖项、调用链条和工作流程，让 AI 真正理解代码的底层逻辑。

它解决了什么问题？

1.2 为什么要全局安装和全局调用？

如果你同时开发多个项目，经常需要在不同的 Trae 窗口间切换，那么全局配置是唯一科学的方式：

GitNexus 官方支持这种“全局注册表”机制：每个项目运行 analyze 后会在全局注册，MCP 服务器启动时自动识别所有已索引项目。

第2章：安装前的准备

2.1 环境要求

2.2 检查 Node.js 安装

# 打开 PowerShell，输入
node --version

预期输出：

v18.0.0 或更高

如果没有安装，访问 nodejs.org 下载 LTS 版本，安装后重启 PowerShell。

2.3 确认你的项目路径

假设你有多个项目：

• Z:\www\wwwroot\project-a
• Z:\www\wwwroot\project-b
• D:\work\legacy-system

记下这些路径，后面都要用到。

第3章：GitNexus 全局安装

3.1 以管理员身份打开 PowerShell

为什么需要管理员权限？
全局安装需要写入系统目录，需要管理员权限。

操作：

1. 按 Win + X，选择 “Windows PowerShell(管理员)”
2. 如果弹出 UAC 提示，点击 “是”

3.2 执行全局安装

# 全局安装 gitnexus
npm install -g gitnexus

安装过程示例：

added 189 packages in 8s

32 packages are looking for funding
  run `npm fund` for details

3.3 验证全局安装

# 查看全局安装列表
npm list -g --depth=0

输出中应包含 gitnexus@1.3.11。

# 直接运行命令验证
gitnexus --version
# 或
gitnexus --help

如果显示帮助信息，说明全局安装成功！

3.4 可能遇到的安装问题

第4章：为每个项目建立索引（只需一次）

这是最关键的一步！每个项目只需要执行一次，GitNexus 会在全局注册表中记录该项目。

4.1 进入项目目录并分析

# 为项目A建立索引
cd Z:\www\wwwroot\project-a
gitnexus analyze

# 为项目B建立索引
cd Z:\www\wwwroot\project-b
gitnexus analyze

# 为项目C建立索引
cd D:\work\legacy-system
gitnexus analyze

执行过程详解：

🔍 Analyzing codebase...
📁 Scanning files... (342 files found)
🔎 Parsing source code...
📊 Building knowledge graph...
✅ Analysis complete! Index stored in: Z:\www\wwwroot\project-a\.gitnexus
📝 Registered in global registry: ~/.gitnexus/registry.json

注意：第一次运行时会下载一些依赖，出现 npm warn 提示是正常的，可以忽略。

4.2 验证索引是否成功

# 查看本地索引文件夹（隐藏的）
dir .gitnexus -Force

# 查看全局注册表
type ~/.gitnexus/registry.json

注册表示例：

{
  "z:\\www\\wwwroot\\project-a": {
    "path": "z:\\www\\wwwroot\\project-a",
    "indexedAt": "2026-03-11T10:30:00.000Z"
  },
  "z:\\www\\wwwroot\\project-b": {
    "path": "z:\\www\\wwwroot\\project-b",
    "indexedAt": "2026-03-11T10:32:00.000Z"
  },
  "d:\\work\\legacy-system": {
    "path": "d:\\work\\legacy-system",
    "indexedAt": "2026-03-11T10:35:00.000Z"
  }
}

4.3 查看所有已索引项目

# 使用 gitnexus 命令查看
gitnexus list

输出示例：

📋 Indexed repositories:
  1. z:\www\wwwroot\project-a (indexed: 2026-03-11)
  2. z:\www\wwwroot\project-b (indexed: 2026-03-11)
  3. d:\work\legacy-system (indexed: 2026-03-11)

第5章：在 Trae 中配置全局 MCP

5.1 找到 Trae 的全局 MCP 配置位置

Trae 的 MCP 配置位置通常有：

本教程使用全局配置，确保一次配置，所有项目生效。

5.2 编写 MCP 配置（最关键的部分！）

{
  "mcpServers": {
    "gitnexus": {
      "command": "gitnexus",
      "args": ["mcp"]
      // ⚠️ 注意：这里绝对不能加 cwd 参数！
      // 加了 cwd 就变成单项目模式了
    }
  }
}

为什么不能加 cwd？

5.3 完整的配置步骤

1. 打开 Trae 的全局配置目录

   # 进入 Trae 配置目录
   cd ~\.trae
   
   # 查看是否存在 mcp.json
   dir mcp.json

2. 编辑或创建 mcp.json

   # 用记事本打开
   notepad mcp.json

3. 粘贴完整配置

   {
     "mcpServers": {
       "gitnexus": {
         "command": "gitnexus",
         "args": ["mcp"]
       }
     }
   }

4. 保存文件（Ctrl+S）

5.4 验证配置是否正确

# 测试 MCP 服务器能否启动
gitnexus mcp

如果没有任何输出（只有光标闪烁），说明 MCP 服务器已成功启动。按 Ctrl+C 退出。

第6章：多项目使用指南

6.1 在 Trae 中提问

配置好全局 MCP 后，你可以在任何 Trae 窗口中这样提问：

方式1：让 AI 自动识别项目
AI 会通过当前 Trae 打开的项目路径自动匹配 repo 参数。

方式2：手动指定项目（当有歧义时）

在项目 "z:\www\wwwroot\project-a" 中查找用户登录相关的代码

方式3：查看所有可用项目

gitnexus://repos

这个资源会列出所有已索引的仓库。

6.2 常用查询示例

6.3 在多项目间切换

假设你同时打开三个 Trae 窗口：

完全无缝切换，无需任何额外配置！

第7章：进阶技巧

7.1 自动配置 MCP（官方推荐）

GitNexus 提供了自动检测编辑器的功能：

# 在任意目录运行
gitnexus setup

这个命令会自动：

• 检测本地安装的编辑器（Cursor、Claude Code、Windsurf 等）
• 写入正确的全局 MCP 配置
• 你只需要运行一次

7.2 更新项目索引

当代码变化后，需要更新索引：

cd 你的项目目录
gitnexus analyze

这会增量更新，只分析变化的文件，速度很快。

7.3 查看索引状态

# 在当前项目目录查看
gitnexus status

# 查看所有项目
gitnexus list

7.4 清理索引

# 清理当前项目索引
gitnexus clean

# 清理所有项目索引（慎用）
gitnexus clean --all --force

第8章：常见问题排查

❌ 问题1：MCP 启动失败，报“No indexed repositories”

现象：

Error: No indexed repositories. Run: gitnexus analyze

原因：MCP 服务器找不到全局注册表，或者注册表为空。

解决：

# 1. 确认是否已为项目运行 analyze
cd 你的项目目录
gitnexus status

# 2. 如果没有索引，运行
gitnexus analyze

# 3. 确认全局注册表存在
type ~/.gitnexus/registry.json

❌ 问题2：查询时指定了 repo 但仍然报错

现象：指定了 "repo": "z:\\path" 但返回找不到。

原因：路径格式不匹配。全局注册表中的路径是绝对路径，必须完全一致。

解决：

# 查看注册表中的确切路径
type ~/.gitnexus/registry.json

# 复制粘贴确切的路径到查询中

❌ 问题3：有很多 npm warn 提示

现象：看到 deprecated、cleanup Failed 等警告。

真相：这些完全可以忽略！ 不影响 GitNexus 的正常使用，只是 npm 在抱怨一些依赖包的问题。

❌ 问题4：MCP 配置了但 Trae 不识别

现象：配置后 Trae 没有显示 MCP 已连接。

解决：

1. 确认配置文件位置正确（全局配置 vs 项目配置）
2. 确认 JSON 格式正确（没有多余逗号）
3. 重启 Trae
4. 手动测试 MCP 服务器：gitnexus mcp

❌ 问题5：新项目加入后，MCP 不识别

现象：为新项目运行了 analyze，但 Trae 中查询不到。

解决：

# 1. 确认新项目已注册
gitnexus list

# 2. 重启 Trae 或重新加载 MCP 连接
# 大多数编辑器会自动检测到新项目，不需要重启

第9章：完整工作流示例

场景：同时开发三个项目

项目清单：

• project-a：电商前端（React）
• project-b：支付服务（Node.js）
• project-c：管理后台（Vue）

第一天：初始化配置

# 1. 全局安装 GitNexus（只需一次）
npm install -g gitnexus

# 2. 为每个项目建立索引（每个项目一次）
cd Z:\www\project-a
gitnexus analyze

cd Z:\www\project-b
gitnexus analyze

cd Z:\www\project-c
gitnexus analyze

# 3. 验证所有项目已注册
gitnexus list

# 4. 配置 Trae 全局 MCP
notepad ~\.trae\mcp.json
# 粘贴配置：{"mcpServers":{"gitnexus":{"command":"gitnexus","args":["mcp"]}}}

# 5. 重启 Trae

日常开发：无缝切换

上午：在 project-a 中工作

在 Trae 中提问：“这个项目的购物车组件依赖哪些模块？”
AI 自动在 project-a 中查询，返回依赖图

下午：切换到 project-b

在 Trae 中提问：“支付接口的调用链是怎样的？”
AI 自动在 project-b 中查询，无需任何重新配置

晚上：处理 project-c 的 BUG

在 Trae 中提问：“这个 BUG 可能影响哪些管理后台功能？”
AI 自动在 project-c 中分析影响范围

第10章：总结与最佳实践

10.1 核心要点回顾

10.2 最佳实践

1. 项目索引只需一次：新项目 clone 下来后，第一件事就是运行 gitnexus analyze
2. 定期更新索引：代码大幅变动后，运行 gitnexus analyze 更新知识图谱
3. 查看全局注册表：用 gitnexus list 确认所有项目都已注册
4. 配置只做一次：全局 MCP 配置好后，再也不用为每个项目操心

10.3 与 Fondamenta ArchCode 的配合

两者可以共存，互不冲突。

📝 附录：命令速查表

教程信息：

• 工具版本：gitnexus@1.3.11
• 适用平台：Windows（macOS/Linux 用户请调整路径格式）
• 最后更新：2026年3月11日

现在你的 Trae 已经拥有了“代码洞察超能力”！无论开多少个项目窗口，都能享受 AI 深度理解代码的能力。如果还有问题，欢迎随时交流。