Qt Creator 6.0.1 集成 Git 实战：手把手教你免终端配置 Gitee 仓库（附 SSH 密钥避坑指南）

Qt Creator 6.0.1 图形化 Git 全流程指南：从零配置到 Gitee 代码托管

在 Qt 开发中，版本控制是项目管理不可或缺的一环。对于习惯图形界面操作的开发者来说，频繁切换终端输入 Git 命令既影响效率又增加学习成本。Qt Creator 6.0.1 内置的 Git 插件提供了完整的版本控制功能，让我们可以在熟悉的 IDE 环境中完成所有 Git 操作。本文将带你完全通过 Qt Creator 的图形界面，实现从本地仓库初始化到 Gitee 远程仓库关联的全过程，特别针对 SSH 密钥配置等常见问题进行深度解析。

1. 环境准备与基础配置

在开始之前，请确保你的开发环境满足以下条件：

• 已安装 Qt Creator 6.0.1 或更高版本
• 系统已安装 Git（Qt Creator 需要调用 Git 命令行工具）
• 拥有有效的 Gitee 账号

验证 Git 安装： 在 Qt Creator 中，点击菜单栏的"工具"→"选项"，左侧选择"版本控制"→"Git"。在"路径"选项卡中，确保 Qt Creator 能自动检测到 Git 可执行文件路径（通常为/usr/bin/git或C:\Program Files\Git\bin\git.exe）。如果未自动检测到，需要手动指定 Git 安装路径。

提示：Windows 用户建议安装 Git 时选择"Use Git from the Windows Command Prompt"选项，这样系统会自动配置环境变量。

配置全局用户信息： 虽然我们主要使用图形界面操作，但 Git 仍需要基本的用户信息来记录提交者身份。在 Qt Creator 的 Git 配置页面，找到"全局配置"部分，添加以下两项：

• user.name：你的用户名（如张三）
• user.email：与 Gitee 账号关联的邮箱地址

这些信息会保存在全局 Git 配置中，用于标识代码提交者身份。

2. 创建与初始化本地 Git 仓库

对于已有 Qt 项目，将其纳入版本控制的第一步是初始化本地仓库。Qt Creator 提供了完整的图形化操作流程：

1. 打开你的 Qt 项目（.pro文件）
2. 点击菜单栏的"工具"→"Git"→"创建仓库..."
3. 在弹出的对话框中，确认仓库创建路径为当前项目目录
4. 点击"创建"按钮完成初始化

初始化成功后，Qt Creator 会在项目目录下创建隐藏的.git文件夹，这是 Git 存储所有版本控制数据的核心目录。此时，项目导航面板中的文件图标旁会出现版本控制状态标识：

• 蓝色问号：未跟踪的新文件
• 绿色加号：已暂存的修改
• 黄色箭头：有未暂存的修改
• 无图标：文件与仓库中一致

首次提交操作：

1. 右键点击项目根目录，选择"Git"→"提交..."
2. 在提交面板中，勾选需要纳入版本控制的文件
3. 输入有意义的提交信息（如"初始项目框架"）
4. 点击"提交"按钮完成首次提交

注意：首次提交建议包含项目的基本框架文件，如.pro、主要源文件和头文件，但应排除自动生成的构建目录（如build-*）和 IDE 特定文件（如.user）。

3. 配置 Gitee 远程仓库连接

在将代码推送到 Gitee 之前，需要先在 Gitee 上创建远程仓库并配置连接。我们提供两种认证方式：HTTPS 和 SSH，重点推荐更安全的 SSH 方式。

3.1 Gitee 仓库创建

1. 登录 Gitee 账号，点击右上角"+"→"新建仓库"
2. 填写仓库名称（建议与本地项目名一致）
3. 选择仓库公开性（私有仓库需要 Gitee 企业版）
4. 不勾选"使用 README 文件初始化仓库"（避免后续合并冲突）
5. 点击"创建"按钮完成远程仓库创建

创建成功后，记下仓库的 SSH 地址（格式如git@gitee.com:yourname/repo.git）或 HTTPS 地址。

3.2 SSH 密钥配置与认证

SSH 认证相比 HTTPS 更安全且无需每次输入密码，是推荐的远程仓库连接方式。

生成 SSH 密钥对：

1. 打开终端（仅此一次需要），输入以下命令：

ssh-keygen -t ed25519 -C "your_email@example.com"

2. 按提示选择密钥保存路径（默认~/.ssh/id_ed25519）
3. 设置安全的密钥密码（可选但推荐）

将公钥添加到 Gitee：

1. 复制公钥内容（~/.ssh/id_ed25519.pub文件内容）
2. 登录 Gitee，进入"个人设置"→"SSH 公钥"
3. 点击"添加公钥"，粘贴公钥内容并确认

测试 SSH 连接：

ssh -T git@gitee.com

看到 "Welcome to Gitee.com, YourName!" 表示配置成功。

3.3 Qt Creator 远程仓库配置

1. 在 Qt Creator 中，右键项目选择"Git"→"远程仓库"→"管理远程..."
2. 点击"添加"，输入远程名称（通常为origin）
3. 在 URL 处粘贴 Gitee 仓库的 SSH 地址
4. 点击"确定"保存配置

此时，Qt Creator 会自动将远程仓库信息写入项目的.git/config文件。

4. 代码推送与分支管理

完成远程仓库配置后，就可以将本地代码推送到 Gitee 了。Qt Creator 的图形界面简化了这一过程。

4.1 首次推送代码

1. 右键项目选择"Git"→"远程仓库"→"推送..."
2. 在推送对话框中：
   • 选择远程仓库（origin）
   • 选择要推送的本地分支（如master）
   • 勾选"设置上游分支"（建立追踪关系）
3. 点击"推送"按钮完成操作

首次推送可能需要输入 SSH 密钥密码（如果生成密钥时设置了）。推送成功后，刷新 Gitee 仓库页面即可看到上传的代码。

4.2 分支创建与切换

在团队协作中，合理的分支策略至关重要。Qt Creator 提供了完整的分支管理功能：

创建新分支：

1. 右键项目选择"Git"→"分支"→"创建分支..."
2. 输入新分支名称（如feature/login）
3. 选择基于哪个分支创建（通常为master）
4. 勾选"切换到此分支"立即使用新分支
5. 点击"创建"按钮完成

分支推送： 新创建的分支仅存在于本地，需要推送到远程：

1. 右键项目选择"Git"→"远程仓库"→"推送..."
2. 选择新创建的分支
3. 勾选"设置上游分支"
4. 点击"推送"

分支切换：

1. 右键项目选择"Git"→"分支"→"切换分支..."
2. 从列表中选择目标分支
3. 点击"切换"按钮

提示：切换分支前请确保当前分支的修改已提交或储藏，否则可能导致冲突。

5. 日常开发中的版本控制操作

在日常开发中，以下几个 Git 操作最为常用，Qt Creator 都为它们提供了图形化实现：

5.1 提交更改

1. 右键项目或修改的文件选择"Git"→"提交..."
2. 在提交面板中：
   • 查看文件差异（双击文件打开对比视图）
   • 勾选要提交的更改
   • 输入清晰的提交信息
3. 点击"提交"按钮

5.2 同步远程更改（拉取）

1. 右键项目选择"Git"→"远程仓库"→"拉取..."
2. 选择远程分支（通常为当前分支的上游分支）
3. 点击"拉取"按钮

如果远程有更改而本地也有未推送的提交，可能会产生合并冲突，Qt Creator 会提供图形化冲突解决工具。

5.3 储藏与恢复临时更改

当需要临时切换分支但不想提交当前修改时，可以使用储藏功能：

储藏更改：

1. 右键项目选择"Git"→"储藏..."
2. 输入储藏信息
3. 点击"储藏"按钮

恢复储藏：

1. 右键项目选择"Git"→"储藏管理器..."
2. 选择要恢复的储藏条目
3. 点击"恢复"按钮

6. 常见问题与解决方案

即使使用图形界面，仍可能遇到一些 Git 相关问题。以下是几个典型问题及解决方法：

6.1 认证失败问题

现象：推送时提示认证失败或权限被拒绝。

解决方案：

1. 确认使用的是 SSH 地址而非 HTTPS
2. 检查 SSH 密钥是否已正确添加到 Gitee
3. 在终端测试 SSH 连接是否正常
4. 对于 Windows 用户，确保 Git 的ssh-agent服务已启动并加载了密钥

6.2 分支无上游错误

现象：推送时提示 "The current branch has no upstream branch"。

解决方案：

1. 在推送时勾选"设置上游分支"选项
2. 或手动设置上游分支：
   • 右键项目选择"Git"→"分支"→"配置上游..."
   • 选择远程分支作为上游

6.3 合并冲突解决

现象：拉取时提示合并冲突。

解决方案：

1. 在 Qt Creator 的"版本控制"视图中查看冲突文件
2. 双击冲突文件打开合并工具
3. 手动选择要保留的更改或编辑合并结果
4. 标记冲突为已解决
5. 完成合并提交

7. 高级配置与技巧

对于希望更深入使用 Git 功能的开发者，Qt Creator 还提供了一些高级配置选项：

7.1 Git 忽略文件配置

通过.gitignore文件可以排除不需要版本控制的文件。Qt 项目常见的忽略项包括：

# 构建目录 build-*/ # IDE 特定文件 *.user *.user.* # 编译生成文件 *.o *.moc *.qrc.d

在 Qt Creator 中，可以右键项目选择"添加新文件..."→"常规"→"文本文件"，命名为.gitignore并添加上述内容。

7.2 子模块支持

对于包含子模块的项目，Qt Creator 也提供了图形化支持：

添加子模块：

1. 右键项目选择"Git"→"子模块"→"添加子模块..."
2. 输入子模块仓库 URL 和本地路径
3. 点击"添加"按钮

更新子模块：

1. 右键项目选择"Git"→"子模块"→"更新子模块..."
2. 选择要更新的子模块
3. 点击"更新"按钮

7.3 图形化日志查看

Qt Creator 内置了强大的提交日志查看器：

1. 右键项目选择"Git"→"查看历史..."
2. 在日志视图中可以：
   • 查看提交历史图表
   • 查看每次提交的详细信息
   • 比较不同版本间的差异
   • 创建标签或重置到特定版本

8. 图形化与命令行的协同使用

虽然本文重点介绍图形化操作，但在某些复杂场景下，结合命令行能更高效解决问题。Qt Creator 提供了便捷的命令行集成：

打开终端： 在 Qt Creator 中，点击左下角的"终端"按钮（或按Alt+T），即可打开集成终端，自动定位到项目目录。

常用 Git 命令参考：

# 查看状态 git status # 查看远程仓库信息 git remote -v # 查看分支关系图 git log --graph --oneline --all # 重置到特定提交 git reset --hard <commit-hash>

提示：在 Qt Creator 的"版本控制"视图中，大多数操作都有对应的右键菜单选项，建议优先使用图形界面。