1. 项目背景与方案选型1.1 为什么用TortoiseGit而不是命令行很多刚开始用Git的朋友都遇到过这个场景代码写完了想推到远端仓库但打开命令行工具一看到git push、git rebase、git cherry-pick这些命令就开始犯怵。不是命令记不住就是参数写错一顿操作下来代码没推上去反倒把本地分支搞得一团糟。TortoiseGit就是冲着这个痛点来的。它把Git的核心操作全部封装成右键菜单你不需要背任何命令所有的提交、推送、拉取、分支切换都能通过图形界面完成。实际上它的设计逻辑和Windows文件管理器的操作习惯高度一致——你平时怎么复制粘贴文件就怎么提交代码几乎没有额外的学习成本。至于Gitee这边它是国内使用最广泛的Git代码托管平台之一本身不挑客户端无论你是用命令行、TortoiseGit、VS Code还是IDEA都能流畅对接。选择Gitee的一个重要原因是它的中文界面和本地化体验做得比较到位对于国内开发者来说无论是注册账号、创建仓库还是配置SSH密钥整个流程都比国外平台要顺畅得多而且访问速度也稳定不需要额外操心网络问题。1.2 这套组合适合什么样的使用场景如果你符合下面任意一条那这篇文章就是写给你的Git新手之前用过SVN或者干脆没用过版本控制工具想找一个迁移成本最低的方案。Windows用户日常开发环境就是Windows不想为了Git单独去折腾命令行工具。个人项目或小团队协作项目规模不大不需要特别复杂的分支管理策略核心诉求是“代码能安安全全地放到远端”。配合IDE使用但不想依赖IDE比如你用某款编辑器写代码它自带的Git插件偶尔抽风你想有一个独立于IDE的、更稳定的图形化Git工具作为备选甚至主力。在这套方案下我后面会演示一个典型的操作路径在Gitee上创建空白仓库用TortoiseGit把本地已经写好的代码完整推上去然后顺便把SSH免密配置好以后提交推送不再每次输账号密码。2. 前期准备Gitee仓库创建与SSH密钥配置2.1 在Gitee上创建一个空白仓库不管你本地代码处于什么状态第一次上传之前总得先在Gitee上把“容器”准备好。登录Gitee之后点击右上角的“”号选择“新建仓库”或者直接进仓库页面点“创建仓库”进入创建表单。这里有几个关键选项需要注意仓库名称只允许字母、数字、下划线和中划线不能有中文和空格。建议用英文小写加中划线的方式命名比如my-blog-system和项目实际功能对应上就好。路径这个会自动根据仓库名称生成一般不用手动改。开源许可证默认是“无”。如果这是私人学习项目选“无”完全没问题如果后面要开源再根据项目性质选择MIT、Apache 2.0之类的许可证就行。这个选项创建之后随时能改不用过度纠结。初始化仓库这里非常关键。如果你本地已经有代码文件了一定不要勾选“使用Readme文件初始化这个仓库”。因为一旦Gitee上生成了初始化的提交记录而本地仓库又是一个全新的、没有任何提交历史的状态两者关联时就会出现分叉处理起来比较麻烦。后面我会详细说怎样避免这个问题。建好仓库之后页面上会显示两种远程仓库地址HTTPS地址和SSH地址。先记下这个SSH地址形如gitgitee.com:用户名/仓库名.git后面配置TortoiseGit要用。2.2 用TortoiseGit生成SSH密钥对SSH密钥的作用是让你在推送代码时不必每次输入Gitee的账号密码。原理是本地生成一对密钥私钥留在本机公钥上传到Gitee推送时服务器用公钥验证你的身份确认是本机在操作就放行。这个功能很多人第一次用容易卡住其实步骤不多在桌面或任意文件夹空白处右键选择“TortoiseGit”再点“Puttygen”。打开PuTTY Key Generator窗口后直接点“Generate”按钮。在窗口空白区域来回移动鼠标直到进度条走完这是为了收集随机数生成密钥。生成完成后点击“Save private key”保存私钥。这里会弹窗提醒你“是否保存未保护的私钥”意思是生成的密钥没有设置口令保护如果选择“是”就保存一个不需要密码的私钥点“是”就行。复制窗口上方那一长串以ssh-rsa开头的公钥内容后面要粘贴到Gitee上。顺手把私钥文件保存到一个安全的位置比如C:\Users\你的用户名\.ssh\目录下文件名随意比如id_rsa_putty方便之后加载。这里有个细节容易让新手疑惑TortoiseGit默认生成的密钥格式是PuTTY的.ppk格式和OpenSSH的密钥格式不一样。Gitee本身两种格式都支持但如果你用TortoiseGit的PuTTY工作模式就需要用上面步骤生成的PPK私钥。后面配置时会看到TortoiseGit的“加载Putty密钥”选项点它选到刚才保存的私钥文件即可。2.3 把公钥添加到Gitee账号回到Gitee网站点击右上角头像进入“设置”左侧菜单选择“安全设置”里的“SSH公钥”。把刚才复制的公钥内容粘贴到“公钥”输入框里标题随便填一个方便识别的名字比如my-windows-pc点“确定”即可。想验证是否配置成功可以在任意文件夹右键打开TortoiseGit的“推送”对话框或者在命令行里执行ssh -T gitgitee.com如果看到提示你确认连接并输入yes然后返回“欢迎”之类的信息就说明密钥配置成功了。不过注意第一次连接SSH时TortoiseGit可能会弹窗询问是否信任主机勾选“是”并保存即可。注意SSH密钥和账号密码是两套独立的认证体系。配置了SSH密钥之后TortoiseGit走SSH协议推送时就不需要账号密码了但如果用的是HTTPS地址还是需要输入用户名密码或私人令牌。所以后面配置远程地址时尽量统一用SSH地址。3. 安装与初始化配置3.1 安装包的获取与安装要点TortoiseGit是开源软件直接去官网下载即可。下载页面有两个版本区别要注意32位版本和64位版本按操作系统位数选择。现在绝大多数机器都是64位不确定的话在“此电脑”上右键属性看一下系统类型。安装包本体和中文语言包是分开的。先装主程序再装LanguagePack两个版本号必须一致否则语言包不会生效。安装过程基本是傻瓜式一路Next就行。但走到安装类型选择时有个选项值得注意它会询问SSH客户端用哪一种。默认选项是TortoiseGitPlink也就是PuTTY的SSH实现另一个是OpenSSH。这个选择影响密钥的管理方式如果前面你用PuTTYgen生成了PPK密钥那就保持默认的TortoiseGitPlink如果你更习惯用OpenSSH的密钥体系也可以选OpenSSH并把公钥、私钥放进.ssh目录。大多数教程默认选第一种既然这篇文章用的是PuTTYgen生成密钥安装时保持默认的Plink即可省得后面配置时对不上。装完主程序后安装中文语言包。安装完成后在桌面空白处右键进入“TortoiseGit”菜单下的“Settings”在“General”页面的“Language”下拉框里选择“中文简体”确定之后界面就变成中文了。3.2 首次运行设置用户名、邮箱和网络代理首次在任何文件夹内右键执行Git操作时TortoiseGit会弹出“设置”对话框让你填写Git用户信息和网络配置。两个关键字段姓名会出现在你的提交记录上比如“张三”。建议和Gitee账号昵称保持一致方便别人认出是你提交的代码。电子邮件同样会记录在每次提交里。Gitee的提交邮箱可以是注册邮箱也可以是Gitee分配的“用户名用户.noreply.gitee.com”这种隐私邮箱。填哪个都行但建议填一个自己能长期使用的因为历史提交里会一直保留这个信息。这里有个容易踩的坑本地设置的姓名和邮箱和Gitee账号没有自动绑定关系。推送代码时Gitee会读取你本地提交记录里的用户信息。如果你本地填的邮箱不是Gitee账号的绑定邮箱Gitee收到推送后该次提交不会正确关联到你的账号头像和主页上看起来就像是一个“陌生人”提交的代码。虽然不影响代码本身的安全但维护起来很别扭。网络设置一般保持默认“自动检测”或“不使用代理”即可。除非你的网络环境特殊否则不需要专门配置代理服务器。3.3 初始化本地Git仓库配置完成后接下来把本地项目目录变成Git仓库。假设你的项目代码位于D:\work\my-project打开这个文件夹在空白处右键会看到菜单里多了“Git 在这里创建版本库”这个选项点击它。弹窗里有两个选项纯版本库裸仓库用于服务端保存代码工作区没有实际文件一般用不到。普通版本库完整复制工作树这就是我们需要的会在当前目录生成一个.git隐藏文件夹记录所有版本历史。选择第二个点击确定即可。初始化完成后文件夹里会多出一个.git目录默认隐藏看不到是正常的。此时如果你在文件夹内右键选择“TortoiseGit” - “提交”会看到所有文件都变成了“新增”状态。这一步做完本地仓库就建好了。接下来要做的就是把本地仓库和Gitee上刚创建的仓库关联起来。4. 核心实操TortoiseGit上传代码全流程4.1 添加远程仓库地址并切换到SSH在项目文件夹内右键选择“TortoiseGit” - “设置”进入“Git” - “远端”配置页面。在“远端”一栏点击“添加”给它起一个名字习惯上叫origin这是Git世界的默认远程仓库名称。然后在“URL”输入框里粘贴之前复制的SSH地址形如gitgitee.com:xxx/xxx.git。“推送URL”一般和URL保持一致不用单独填。填完之后点击“确定”保存。这里有一个操作建议配好远端之后先做一次“拉取”或“获取”确认TortoiseGit能通过SSH正常连上Gitee。如果第一次连接时弹窗询问是否信任主机勾选“是”并保存。这一步能提前暴露SSH配置问题避免后面推送时才发现连不上。4.2 首次提交把本地文件纳入版本管理在项目文件夹内右键选择“Git 提交”进入提交对话框。第一次提交时所有文件都会出现在“版本化的文件”列表里状态是“新增”。你需要勾选所有要提交的文件或者直接全选。在“提交信息”一栏写清楚这次提交的内容比如“初始化项目完成登录模块基础代码”。确认下方的“作者”和“日期”信息无误。点击“提交”。有一个小习惯值得养成不要把提交信息写成“update”或者“修改”这种毫无信息量的话。因为Git的提交历史就是你的项目开发日志三个月后你回头看某个提交如果所有提交信息都写着“update”想定位问题会非常痛苦。好的提交信息应当简明扼要地说明“这版做了什么”比如“修复登录超时bug”或者“新增用户列表筛选功能”。首次提交完成之后代码还在本地仓库里还没有到Gitee上。接下来就是最后一步——推送。4.3 推送到Gitee仓库文件提交完成后在同一位置右键选择“TortoiseGit” - “推送”。推送对话框里“远端”选择origin。“本地分支”和“远程分支”一般默认都是master或main保持默认即可。下方“目标”那栏确保没有勾选“强制覆盖”之类的选项首次推送也不需要。逻辑上本地仓库经过一次提交之后和Gitee上的空仓库之间没有分叉推送时会从空仓库的新起点创建分支不会有冲突。点击“确定”后TortoiseGit会弹出进度窗口走SSH协议完成推送。推送成功后进度窗口里会出现类似master - master的提示。这时打开Gitee仓库页面刷新一下就能看到代码已经躺在仓库里了。4.4 新项目首次推送的完整清单为了帮助第一次操作的朋友我把整个过程整理成一个可以直接照做的清单在Gitee创建空白仓库不勾选任何初始化选项。本地代码文件夹内右键选择“Git 在这里创建版本库”选“普通版本库”。右键“TortoiseGit” - “设置” - “远端”添加origin并填入SSH地址。右键“TortoiseGit” - “提交”勾选全部文件填写提交信息执行首次提交。右键“TortoiseGit” - “推送”选择origin点击确定。刷新Gitee页面确认代码已上传。这套流程几乎不需要记任何命令只要按顺序走成功率很高。很多朋友第一次卡住一般就是卡在Gitee仓库初始化勾选、SSH密钥加载或者远端地址填错这三个环节上下面我会专门展开说说这些坑。5. 高频问题与避坑排查实录5.1 推送时提示“Authentication failed”或频繁要求输入密码这是最典型的问题之一基本每次给新手排查都会遇到。出现这个提示说明TortoiseGit没有通过SSH密钥完成身份验证又回头去尝试走账号密码认证了。排查思路按顺序来第一步确认推送地址是SSH格式。如果远端地址填的是https://gitee.com/xxx/xxx.git那无论SSH密钥配得多完美TortoiseGit都会走HTTPS协议自然要你输入账号密码。解决办法是在远端设置里把URL改成SSH地址或者直接在Gitee仓库页面复制SSH地址重新填一遍。第二步确认SSH密钥已经加载。TortoiseGit的“设置” - “网络”里有一个“SSH”设置项。如果你用的是PuTTY格式的密钥这里需要手动指定私钥路径。默认情况下TortoiseGit会尝试使用C:\Users\用户名\.ssh\下的PPK文件但如果你的私钥保存在其他目录就需要在这里设置。点击“SSH客户端”旁的“浏览”选到你的私钥文件并确保“使用PuTTY密钥”的选项被勾选具体选项名可能因版本略有差异。第三步检查Gitee上的公钥是否粘贴完整。公钥是一整行以ssh-rsa开头复制的时候要确保没有遗漏。粘贴到Gitee时不要自作主张换行或加空格否则密钥校验会失败。第四步本地测试连接。在项目文件夹右键打开TortoiseGit的“推送”窗口之前可以先在Git Bash或者PowerShell里执行ssh -T gitgitee.com如果返回的是权限拒绝之类的提示说明密钥有问题回到前面几步排查如果能正常识别用户再去TortoiseGit里推送大概率就顺畅了。5.2 推送时报“refusing to merge unrelated histories”之类的合并冲突这个报错一般是两种情况引起的一种是你创建Gitee仓库时勾选了“使用Readme初始化仓库”Gitee那边有了一个初始提交而本地仓库也有自己的首次提交两边历史没有共同祖先推送时就会拒绝合并。解决办法有两个如果你还没做任何代码提交最简单的方式是在Gitee上删除这个仓库重新创建一个完全不初始化的空白仓库再走一遍推送流程。如果不想删仓库也可以在TortoiseGit的“拉取”或“推送”时使用“允许不相关历史合并”的相关选项对应命令行的--allow-unrelated-histories但说实话对新手来说重新建一个干净仓库更省心能避免很多潜在的合并混乱。另一种情况是你拉取了别人仓库的代码之后在本地做了大量修改远程仓库里同时也有别人的新提交。这种冲突不是本文核心范围但简单说一句优先“获取/拉取”远程最新代码解决本地冲突之后再推送不要硬推。5.3 提交后代码是绿色/红色图标但推送后图标状态没变TortoiseGit会在文件管理器里给文件和文件夹打上状态图标比如绿色对勾表示已提交、红色感叹号表示有冲突、蓝色加号表示新增未提交。每次在TortoiseGit里执行操作后图标会刷新但有时候会卡住或者显示的还是旧状态。遇到这种情况可以在文件夹内右键 - “TortoiseGit” - “刷新”强制更新图标缓存。如果刷新无效检查一下“设置” - “图标叠加”里的选项确认“状态缓存”设置为“默认”或“仅当前目录”并且不是“禁用”。这个属于显示层的小问题不影响代码本身但经常让新手误以为推送失败了所以单独提一下。5.4 换电脑或换系统后推送失败很多人一台电脑换了主机的硬盘或者换了一台新的开发机发现推送到Gitee时又开始要求密码了。原因很简单SSH密钥是跟着本机走的之前的私钥没有迁移到新电脑或者迁移了但TortoiseGit没有正确加载。解决办法分两步把之前保存的PPK私钥文件拷贝到新电脑的某个固定位置比如C:\Users\你的用户名\.ssh\。在TortoiseGit的“设置” - “网络”里指定这个私钥文件。如果你当时保存私钥时设置了口令passphrase加载私钥时还需要输入口令。为了避免每次推送都输一遍可以在TortoiseGit的“设置”里把认证信息保存起来Pageant相关的设置但这样做有安全风险取决于你自己对便捷和安全的权衡。另外如果你是重装了系统、私钥已经丢了那就只能用老办法解决在Gitee里删掉旧的公钥用新电脑重新生成一对密钥把新公钥添加进去。旧私钥丢失后旧公钥就成了一张作废的钥匙留着还可能有安全隐患建议顺手删掉。5.5 中文乱码问题偶尔有朋友反馈TortoiseGit提交后打开Gitee网页端发现提交信息是乱码。这个一般是编码问题。Windows下TortoiseGit默认使用系统编码提交如果系统区域设置不是UTF-8中文提交信息就可能出现乱码。处理方式在TortoiseGit“设置” - “Git” - “编辑全局.gitconfig”在[i18n]段落里加上[gui] encoding utf-8 [i18n] commitEncoding utf-8 logOutputEncoding utf-8保存后重新提交一次新的提交信息应该就能正常显示中文了。旧提交已经乱码的话只能通过git rebase重写历史来修复对新手来说不建议折腾当作历史记录直接忽略就好。6. 实操心得与效率建议6.1 分支提交的几个建议我见过很多用TortoiseGit的人永远是直接在master或main分支上提交代码。个人项目这么干没问题但一旦项目要长期维护或者后续要多人在同一个仓库里协作习惯就很重要了。建议在开始写新功能时先在TortoiseGit里右键 - “Switch/Checkout”选择“创建新分支”给功能建一个专门的分支比如feature/login-page。功能开发完毕测试没问题之后再合并回主分支。TortoiseGit的分支切换和合并都是图形化操作成本很低但能帮你把项目历史整理得清爽很多。6.2 提交信息里带上编号如果你有项目管理系统比如禅道、Jira之类的提交信息里建议带上任务编号或需求编号例如“修复用户头像上传失败问题 #1234”。这样后续不管是自己回溯还是同事在Gitee里看提交历史都能直接对应到业务需求排查问题的效率会高很多。6.3 .gitignore文件务必尽早创建很多新手第一次上传代码会把node_modules、target、bin、obj这些编译产物或者依赖目录一股脑推上去。这样做的后果是仓库体积迅速膨胀克隆一次项目要下载几百MB甚至几个GB的无关文件而且这些文件对别人来说毫无价值。正确做法是在项目创建之初最晚在首次提交之前就创建.gitignore文件把不需要纳入版本管理的目录和文件类型写进去。如果是Java项目至少忽略target/如果是Node项目忽略node_modules/如果是Python项目忽略__pycache__/和.venv/。TortoiseGit没有自动帮你生成.gitignore的功能但你可以从Gitee创建仓库时的“选择语言模板”里复制一份或者在项目里手动创建一个文本文件改名成.gitignore。已经有文件被提交了也没关系在TortoiseGit里把相关文件从版本库中移除右键 - “删除”并提交然后加上.gitignore就行。只是历史记录里仍然会保留之前提交的大文件如果还没推送到Gitee本地重新初始化仓库是最彻底的补救办法。6.4 定时拉取避免长期不更新如果你一个人维护项目可以很长时间不拉取远程代码因为根本没有其他人往里推。但一旦多人协作就要养成“动手写代码之前先拉取一次”的习惯。TortoiseGit里右键 - “拉取”一键完成不用多解释。长期不拉取等别人推了好几版之后你再推冲突几乎是必然的与其等到硬碰硬的时候再解决不如每天开工顺手拉一次。6.5 保存凭据的小技巧虽然SSH密钥已经能实现免密推送但有些人因为历史原因还在用HTTPS地址每次推送都要输入账号密码确实烦人。TortoiseGit在HTTPS模式下可以保存凭据在“设置” - “Git” - “凭据”里选择“永久保存”或者“每次会话保存”。这样推送时只需输入一次后续就自动带上了。不过要注意凭据是明文保存在Windows凭据管理器里的如果你用的是公司电脑要评估一下这个做法是否合适。用TortoiseGit这套流程整体体验就是“能在界面上点的绝不用命令去背”。对新手来说它把Git的复杂度降了一个台阶让你把注意力集中在写代码本身对老手来说它也是一个可靠的后备工具尤其适合在IDE的Git插件抽风时快速救场。我的建议是初学者先用TortoiseGit把Git的基本流程和概念吃透等理解了提交、分支、合并、推送这些动作背后的含义再去尝试命令行也不迟。工具只是手段核心是理解版本管理到底在管理什么。