Troubleshooting

故障排查

先收集安全信息

1. VS Code 版本；
2. git --version；
3. 操作系统与架构；
4. TriForge 版本和扩展 ID；
5. 当前是否为 Remote SSH/WSL/Dev Container；
6. “输出” → “TriForge Git”中的错误；
7. 去除凭据后的 git remote -v；
8. 哪个平台、公共还是自建实例。

不要在 Issue 中提交 Token、带凭据 URL、完整私有域名清单或敏感仓库内容。

图标或按钮不见了

整个 TriForge 活动栏图标不见

1. 确认 zhangxh-math.triforge-git 已启用；
2. 在活动栏空白处右键，勾选“TriForge Git”；
3. 运行“Developer: Reload Window”；
4. 检查是否同时安装了 local-lab.triforge-git 并产生冲突；
5. 查看扩展宿主日志。

只能看到“提交与同步”或“分支、更改与远程”其中一个

VS Code 记住了隐藏/移动状态：

1. 命令面板运行“View: Reset View Locations”；
2. 重新打开 TriForge；
3. 右键侧栏标题/空白处，确认三个视图全部勾选；
4. 拖动视图之间分隔线，避免某一视图高度被压到接近零。

“本地分支 main 已存在，但跟踪的是 gitlab-git/main，不是 github/main”

含义：

• 你选择了远程分支 github/main；
• 本机已经有名为 main 的分支；
• 这个本地 main 当前 upstream 是 gitlab-git/main；
• Git 不能让同一个本地分支同时跟踪两个 upstream。

选项：

• 切换现有分支：继续使用本地 main 和它原来的 GitLab upstream；
• 使用其他名称：例如创建 main-github，让它跟踪 github/main；
• 取消：先看 Graph，再决定哪一个应当作为主要 Pull 来源。

这不妨碍同步 Push 到多个平台；upstream 只决定普通 Pull 的默认来源。

连接 GitLab 后仍弹“Connect to GitLab”登录框

先判断弹窗来自谁：

• 点击 VS Code 内置源代码管理器的 Push/Pull：可能触发 Git Credential Manager 或 GitLab 相关扩展；
• 在终端运行 git push：使用系统 Git 的 credential helper；
• 点击 TriForge 自己的“推送”：应使用 TriForge SecretStorage Token，并禁止交互式凭据窗口。

TriForge 的平台连接不会全局登录 Git，也不会修改 VS Code 内置 Git 扩展的认证状态。要避免弹窗，请从 TriForge 的按钮发起对应操作，或者单独正确配置系统 Git 凭据。

若 TriForge 按钮本身仍弹窗，检查 remote 是否为 SSH、自定义 helper、另一个主机或不匹配自建路径前缀；这些地址不会获得 TriForge PAT。

“没有源代码管理提供程序”或不是仓库

• 确认打开的是文件夹，不是单个文件；
• 点击“初始化本地仓库”；
• 多根工作区选择正确根目录；
• 检查 .git 是否存在且当前用户有权限；
• 子目录仓库或 worktree 若识别异常，在其真实根目录单独打开；
• 未受信任工作区先评估来源，再决定是否信任。

连接验证失败

401 Unauthorized

• Token 复制不完整或已撤销；
• Token 已到期；
• 实例要求 SSO/额外授权；
• 选错平台种类；
• 输入了 API URL 而不是实例首页 URL。

403 Forbidden

• Token scope 不足；
• 管理员禁用 PAT 或 API；
• 账号被限制；
• GitLab DPoP/组织策略要求额外认证。

404 Not Found

• 自建实例路径前缀缺失；
• 首页 URL 中误加 /api/v4 或 /api/v1；
• 反向代理没有转发 API；
• 服务端用 404 隐藏无权限资源。

证书错误

参见 自建实例。不要关闭 TLS 校验。

Git Push 成功，但 TriForge API 连接失败

Git Push 和 API 请求由不同客户端处理：

• Git 使用系统 git 和它的证书/代理配置；
• API 使用 VS Code 扩展宿主的 HTTPS 栈。

因此 Git Credential Manager 已登录、系统 Git 信任企业 CA，并不自动让扩展 API 也通过。反向情况也可能发生。

搜索结果为空

• 尝试留空列出近期仓库；
• 检查 Token 的私有仓库读取权限；
• 确认仓库在 GitHub fine-grained Token 选择范围；
• 查看是否有“某连接失败”的标题；
• 查看输出日志中的限流/网络错误；
• 调整搜索词；各平台搜索语义不同；
• 单连接最多返回设置上限内的结果。

Push 未创建缺失仓库

检查：

• 该连接在勾选框中是否仍勾选；
• Token 是否有创建仓库权限；
• 当前账号是否被管理员禁止创建项目；
• 当前个人 namespace 是否已经存在同名仓库；
• 仓库名是否满足平台规则；
• 平台是否返回 403/422；
• 连接元数据是否在等待期间被修改。

0.5.0 只在当前用户个人命名空间自动创建，不会让你选择组织/群组。

Push 被拒绝

Non-fast-forward

远端有本地没有的提交。Fetch 全部，打开 Graph，合并正确远程分支后再推送。不要立刻 Force Push。

Protected branch

服务端策略不允许直接写入。推送功能分支并使用 Pull/Merge Request。

Authentication failed

• 修改连接并输入新 Token；
• 确认 remote 为精确匹配实例的 HTTPS URL；
• SSH remote 需独立 SSH 认证；
• 检查 Token 仓库内容写权限。

Pull 提示分叉

这是 --ff-only 的保护结果，不是数据损坏：

1. 打开 Graph；
2. 找到本地 HEAD 和目标 remote 分支；
3. 选择“合并”并明确策略；
4. 解决冲突、暂存、继续；
5. 再同步 Push。

Diff 为空

• 可能选错“已暂存/待提交”阶段；
• 文件可能是二进制；
• 文件可能在打开前又发生变化；
• 重命名/删除可能在另一路径条目中；
• 当前没有文本差异；
• 未跟踪文件会直接打开，而不是生成补丁。

刷新状态后重新选择。

Graph 没显示远程位置

• 仓库尚未配置 Git remote；
• 尚未 Fetch，远程跟踪引用不存在；
• remote URL 无法分类且没有匹配的平台连接；
• Graph 达到提交上限；
• remote 只含不存在于当前可见提交范围的引用。

先执行 Fetch 全部，再刷新 Graph。必要时提高 triforge.graph.maxCommits。

颜色难以辨认

0.5.0 使用 VS Code 主题变量，并为深色、浅色、高对比度主题分别设计标签。若仍不清楚：

• 切换官方高对比度主题验证；
• 检查用户 CSS/主题扩展是否覆盖 Webview 颜色；
• 不只看颜色，使用 GH/GL/GT、remote 名和 tooltip 判断；
• 重载窗口排除旧 Webview 缓存。

macOS 中 Terminal 和扩展的 Git 行为不同

查看 macOS 使用说明 中的 PATH 与 /usr/bin/git 说明。0.5.0 没有 Git 路径设置，Dock 启动环境可能不同。

操作卡在 Merge/Revert 状态

• 处理所有冲突并暂存，然后点“继续”；
• 不想保留操作则点“取消操作”；
• 不要手动删除 .git 内的状态文件；
• 若外部工具已经完成/取消，先点击刷新；
• 输出日志仍报错时，在完整备份后使用 Git 原生命令诊断。

如何提交有效 Issue

包含：

• 最小复现步骤；
• 预期行为和实际行为；
• 已脱敏日志；
• VS Code/TriForge/Git/OS 版本；
• 公共实例还是自建实例及大致版本；
• 是否 Remote SSH/WSL/Container；
• 是否能在空测试仓库复现。

绝不要附上 Token 或包含 Token 的完整进程环境。