大龙说学区我见过太多人卡在Git安装这一步：下载链接找不到、装完右键没有Git Bash、刚push就报错、换个电脑又不会配了。这篇文章就针对Windows环境，从零开始把Git装好、配好，再连上Gitee远程仓库，把代码完整推上去。整个过程覆盖下载安装、SSH免密配置、仓库推送、VS Code可视化操作和常见报错排查，适合刚接触版本控制的同学，也适合已经在用但总被奇怪问题卡住的人。
1. 开始之前的准备：Windows下安装Git的正确姿势
1.1 下载版本怎么选
Git的Windows发行版叫Git for Windows，官网地址是git-scm.com/download/win，打开后页面会自动识别当前操作系统的位数，一般直接点“64-bit Git for Windows Setup”就行。
有一点要注意：如果你用的是比较老的32位系统，需要去页面下方的“Older releases”或者“Windows 32-bit”入口找对应版本。现在绝大多数Windows 10/11都是64位，直接下载最新版即可。国内网络访问官网速度不稳定的话，可以用阿里云镜像、淘宝npm镜像等地方下载，搜索“git for windows 镜像”能找到带完整安装包的地址，版本号对得上就行。
1.2 安装过程里最容易选错的几个选项
安装包下载完双击运行，大部分步骤一路Next不会出大问题，但有四个选项会影响后续使用体验，我逐个说下。
第一是安装路径。默认在C:\Program Files\Git，路径带空格其实现代工具都能处理，但我建议改成不带空格不带中文的路径，比如C:\Git。这不是玄学，以前遇到过某些脚本和工具解析带空格的路径时莫名报错，改成纯英文路径后问题消失，属于“没坏处、能避坑”的习惯。
第二是“Select Components”这一步。默认勾选了“Git Bash Here”和“Git GUI Here”，这两个右键菜单一定要保留。日常开发里你随便打开一个文件夹，右键就能进Git Bash，比每次手动切目录方便太多。其他的组件按默认即可。
第三是默认编辑器。如果你装了VS Code，这一步可以直接选“Use Visual Studio Code as Git's default editor”。没有的话选“Use Nano”或者“Use Vim”都行，后面也可以在命令行里改，不影响核心功能。
第四是最关键的“Adjusting your PATH environment”。这个选项有三个单选：
- “Use Git from Git Bash only”：只把Git集成到Git Bash里，cmd和PowerShell里用不了。
- “Git from the command line and also from 3rd-party software”：推荐选这个。
- “Use Git and optional Unix tools from the Command Prompt”：不推荐，会把一堆Unix命令混进Windows命令行环境，容易出乱子。
我见过有人选第一个，结果在VS Code的终端里敲git提示“不是内部或外部命令”，其实就是这一步选错了。选第二个之后，cmd、PowerShell、VS Code自带终端里都能直接用git命令，最省心。
1.3 继续安装时要注意的细节
继续往下，到“Choosing the SSH executable”这一步，默认“Use OpenSSH”就行，除非你电脑系统特别旧导致OpenSSH组件缺失，否则不用改。
“Choosing HTTPS transport backend”同样保持默认“Use the OpenSSL library”，这个跟HTTPS证书校验有关，大多数场景下默认即可。如果你在的公司内网有用自签名证书，后面遇到证书报错再单独配置。
“Line Ending Conversions”是Windows平台特有的坑。建议选第一个“Checkout Windows-style, commit Unix-style line endings”。意思是：拉取代码到本地时自动转成Windows的CRLF，提交时自动转回Unix的LF。这样Windows和Linux/macOS的同事协作时，不会因为换行符差异导致整个文件被标记成修改。如果你的团队里有人专门处理过行尾问题，他们通常会给出更严格的要求，否则默认第一个就是最省事的选择。
“Use MinTTY”这个终端模拟器选项，我建议保持默认选MinTTY。它在中文显示、鼠标选择、复制粘贴这些体验上比Windows自带console窗口舒服得多。
装完之后，在任意文件夹空白处右键，点“Git Bash Here”，输入：
bash复制git --version
能输出版本号就说明安装成功。比如git version 2.45.1.windows.1。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 让Git知道你是谁：首次全局配置
装完Git第一件事不是急着连远程仓库，而是先配置用户身份。因为Git的每一次提交都会把“作者”和“提交者”信息写进记录里，不配的话后面提交会报错，或者提交记录上显示一个乱七八糟的默认用户名。
打开Git Bash，执行：
bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
这里的名字和邮箱建议跟你在Gitee上注册时用的信息一致，这样提交记录里能直接对应到你的Gitee账号。--global的意思是全局生效，这台电脑上以后所有仓库都会用这套身份。
想确认配置是否生效，可以执行：
bash复制git config --global --list
会输出类似这样的内容：
text复制user.name=你的名字
user.email=你的邮箱
这里多说一句Git配置的三个级别，搞懂了这个后面排查问题很有用：
- system级别：整个操作系统所有用户生效，配置文件在Git安装目录下。
- global级别：当前系统用户生效，配置文件一般在
C:\Users\你的用户名\.gitconfig。 - local级别：只对当前仓库生效，配置文件在仓库的
.git/config里。
优先级是local > global > system。如果某个配置你明明设置了却不生效，多半是更上一层的配置把它覆盖了。
3. 打通Gitee：创建远程仓库并配置SSH免密
3.1 在Gitee上创建一个新仓库
登录Gitee官网，右上角点“新建仓库”，进入创建页面。这里有几个字段要说明：
仓库名称用英文小写加连字符，比如my-blog或note-app，不要用中文，不要有大写字母。理论上Git支持中文仓库名，但命令行操作、URL拼接、后续配置都可能出现字符编码问题，没必要给自己埋雷。
路径名会自动关联仓库名，不用单独改。点击“创建”前，仓库默认是私有还是公开，看你的需求：个人代码用私有，想要分享或开源用公开。这里还要先设置“选择许可证”，但如果你不确定选哪个，可以建仓完成后随时在仓库设置里补上。
初始化仓库这个选项要留意：
- 如果你本地已经有一堆代码，打算推上来，就不要勾选“初始化仓库”，不要自动生成README、.gitignore和开源许可证。
- 如果你是空仓库开始，准备直接在网页上写文件或者从零建一个项目，可以勾选。
我实测下来，大多数人第一次用Gitee时本地已经有代码了，所以建议不要勾选，避免后面还要处理远程和本地历史不相关的问题。
仓库创建成功后，页面上会显示两种远程地址：HTTPS和SSH。我推荐用SSH地址，也就是长这样：
text复制git@gitee.com:你的用户名/仓库名.git
这样配好SSH免密之后，以后push、pull都不用输账号密码，体验顺很多。
3.2 生成SSH密钥对并添加到Gitee
在Git Bash里执行这条命令：
bash复制ssh-keygen -t rsa -C "你的邮箱" -b 4096
-t rsa指定密钥类型，-C是注释信息，一般填邮箱，方便自己识别是哪台机器生成的。-b 4096指密钥长度，比默认的2048更安全，虽然生成慢一点，但值得。
回车后会提示你保存位置，默认是C:\Users\你的用户名\.ssh\id_rsa，直接回车接受默认即可。接着会问你是否设置passphrase（口令），如果你追求完全免密，就留空直接回车。如果你在安全要求比较高的环境，可以设一个，但代价是每次用密钥时都要输入口令。
生成完成后，在Git Bash里执行：
bash复制cat ~/.ssh/id_rsa.pub
这个输出就是一整段以ssh-rsa开头的公钥内容。用鼠标选中复制，注意不要漏掉开头和结尾的空格。
然后到Gitee网站右上角头像 > 设置 > 安全设置 > SSH公钥，点“添加公钥”，标题随意填，比如“我的Windows电脑”，把刚才复制的公钥粘贴进去，点确定。
添加完成后，在Git Bash里测试连接：
bash复制ssh -T git@gitee.com
第一次连接时会出现一段提示：
text复制The authenticity of host 'gitee.com (xxx.xxx.xxx.xxx)' can't be established.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
输入yes回车。如果配置成功，会看到类似：
text复制Hi 用户名! You've successfully authenticated, but GITEE.COM does not provide shell access.
看到这句话就说明SSH免密已经通了，非常关键。很多人的问题就出在这一步之前：公钥没复制全、邮箱填错、或者把私钥泄露给了别人，都会导致认证失败。
3.3 免密背后的原理，简单说两句
SSH免密的核心是非对称加密：生成密钥时会产生一对文件，一个私钥保存在本机，一个公钥上传到Gitee。
当Git需要连接Gitee时，Gitee会用公钥加密一段随机数据发给你的客户端，你的Git客户端如果能用私钥解开，就证明“你是私钥的合法持有者”，于是免密通过。整个过程私钥始终不出本机，公钥可以随便分发。
所以一定要记住：id_rsa这个私钥文件千万不要发给任何人，不要提交到代码仓库里，不要上传到网盘。一旦泄露，别人就能以你的身份操作你的仓库。如果不小心泄露了，立刻去Gitee把对应的公钥删掉，重新生成一对。
4. 把本地项目推送到Gitee：完整的实操流程
4.1 初始化本地仓库并完成首次提交
假设你的项目已经在本地某目录里了，比如D:\projects\my-blog。在项目目录里打开Git Bash，执行：
bash复制git init
这会在当前目录生成一个隐藏的.git文件夹，里面保存了仓库的全部版本历史。你可以在文件资源管理器里看到它，但不要手动修改里面的内容，否则可能导致仓库损坏。
接着把项目文件加入暂存区：
bash复制git add .
这个命令会把当前目录下所有文件（除了.gitignore里面忽略的）加入暂存区。这时可以查看一下状态：
bash复制git status
会看到一堆绿色文件名，说明这些文件已经进入暂存区等待提交。
然后提交：
bash复制git commit -m "docs: init project"
双引号里是提交说明。我这边的建议是第一次提交就写清楚这个项目的初始状态，比如“init project”或者“docs: 初始化博客项目”。后文我会专门讲提交规范。
4.2 关联远程仓库并完成第一次推送
回到Gitee仓库页面，复制SSH地址。在本地仓库里执行：
bash复制git remote add origin git@gitee.com:你的用户名/仓库名.git
origin是给远程仓库起的默认名字，相当于一个别名，指向你复制的那个地址。这样以后不用每次都写一长串URL。
接下来看一下当前分支名。新版的Git默认分支可能是master，也可能是main。很多人的第一个坑就在这里：本地是master，Gitee上期望的是main，推上去对不上。建议统一改成main：
bash复制git branch -M main
-M的意思是强制重命名当前分支为main。然后执行：
bash复制git push -u origin main
这里的-u是--set-upstream的简写，作用是把本地main分支和远程main分支建立关联。关联之后，以后直接执行git push或者git pull就能自动对应到正确分支，不用每次带参数。
第一次推送如果成功，会看到类似输出：
text复制Enumerating objects: 5, done.
Writing objects: 100% (5/5), 389 bytes | 389.00 KiB/s, done.
Total 5 (delta 0), reused 0 (delta 0), reused 0 (delta 0)
To gitee.com:你的用户名/仓库名.git
* [new branch] main -> main
branch 'main' set up to track 'origin/main'.
这时刷新Gitee仓库页面，你的代码已经躺在远程仓库里了。
4.3 日常更新流程：提交、拉取、推送
项目跑起来之后，日常操作基本就是三件事：提交本地修改、拉取远端更新、推送本地提交。
改完代码后，先看状态：
bash复制git status
接着把需要提交的文件加入暂存区。如果改动的文件多，可以直接：
bash复制git add .
提醒一句：git add .会把所有改动都加进去，包括可能不想提交的临时配置文件。如果你只想提交特定文件，就写具体路径，比如：
bash复制git add src/App.vue
然后提交：
bash复制git commit -m "fix: 修复登录页面样式问题"
推送之前，如果这是多人协作项目，或者你换了电脑改了代码，最好先拉取一下远端更新：
bash复制git pull
如果远端有别人提交的新内容，Git会自动合并。合并没有冲突的话，再执行：
bash复制git push
就能看到更新已经同步到Gitee了。如果你在pull时遇到冲突提示，Git会标记出冲突文件，需要手动打开文件解决冲突，保留需要的代码，再重新git add、git commit、git push。
4.4 提交信息和分支命名，别随便糊弄
提交信息写的越清楚，后面翻历史越省力。我习惯用这种常见格式：
text复制type(scope): subject
常见type有：
- feat：新功能
- fix：修复bug
- docs：文档调整
- style：样式修改，不改逻辑
- refactor：重构，不改功能
- test：测试相关
- chore：构建、工具链等杂事
比如fix(login): 修复验证码过期后无法刷新，比修改了一点东西强一百倍。别小看提交信息的价值，几个月后你自己回来查历史，看到模糊的提交信息心态会崩。
分支命名建议遵循：主分支叫main，新功能分支用feature/xxx，修复分支用fix/xxx，发布分支用release/xxx。比如feature/user-page、fix/login-timeout。Gitee上创建合并请求时，清晰的分支名能让人一眼看懂意图。
4.5 .gitignore：哪些东西不该提交
创建.gitignore文件，把不需要进版本库的目录和文件写进去，比如：
text复制node_modules/
dist/
.env
*.log
.idea/
.vscode/
.DS_Store
.gitignore的作用不是“删除文件”，而是“告诉Git哪些文件不要跟踪”。它本身需要提交到仓库里，这样团队所有人都遵守同一套忽略规则。有些人会把.env这种含密码的配置文件误提交上去，这个习惯很危险，因为一旦提交到Gitee，从历史记录里翻出来也是可能的。正确做法是never提交这类敏感文件。
如果你已经提交了不该提交的文件，需要先从Git跟踪中移除：
bash复制git rm -r --cached node_modules
--cached表示只取消跟踪，不删除本地文件。之后把.gitignore补上，再提交一次。
5. 用VS Code操作Git：可视化也很顺手
5.1 VS Code的源代码管理面板
装了VS Code之后，不用装额外插件就能用Git基础功能。打开一个包含.git目录的项目，左侧边栏会出现“源代码管理”图标。这里能看到所有未暂存的修改，可以点击“+”号暂存单个文件，也可以直接在上方输入框里写提交信息，然后点“提交”按钮。
提交之后，点击面板顶部的“同步更改”按钮，就等于执行了git pull加git push。对于新手来说，这个流程比命令行直观很多。
VS Code在背后执行的其实还是git命令。如果你在VS Code的输出面板里看到类似：
text复制git -c diff.mnemonicprefix=false -c core.quotepath=false --no-optional-locks status -z
这就是VS Code内部的git调用参数，不用管它，知道是正常现象即可。
5.2 关于回滚：撤销提交到底该怎么点
很多人问：“我在VS Code里把代码已经推到远程仓库了，用撤销上次提交可以回滚吗？”
这里要分情况讲。
如果是本地刚刚提交、还没推送到远程，想撤销这次提交但保留代码改动，可以在VS Code命令面板里搜“Git: Undo Last Commit”，等价于执行：
bash复制git reset --soft HEAD~1
--soft的意思是只撤销提交记录，已经暂存的内容全部保留在工作区。如果你连暂存状态都不要，想彻底回到提交前，可以用--mixed。
如果你不只是撤销提交，而是想把那次提交的所有代码改动也一起丢掉，可以用：
bash复制git reset --hard HEAD~1
这个命令有破坏性，执行前一定确认不需要那些改动了，因为--hard会直接丢弃工作区里对应的修改。
但如果你已经把提交推送到Gitee远程仓库，事情就复杂了。git reset之后需要强制推送才能覆盖远程历史：
bash复制git push --force
这会改写远程仓库的历史。如果是你自己一个人用的仓库，问题不大；如果是多人协作，强制推送会导致其他人的本地记录和远程不一致，可能给大家带来麻烦。这种情况我建议用git revert生成一次反向提交，它不会改写历史，而是增加一个新提交来“抵消”之前的改动：
bash复制git revert HEAD
这样远程历史是完整的，其他人pull下来也不会出问题。简单说：本地没推送随便reset；已经推送了且是多人协作，优先revert。
5.3 VS Code里切换账号和配置远端
VS Code的Git操作会自动读取你电脑上配置的git账号和SSH key。如果你在Git Bash里配置好了SSH免密，VS Code里推送也是直接免密的，不需要重复设置。如果你用HTTPS地址连接远程仓库，VS Code会弹出要求输入用户名和密码的窗口，这时Gitee可能要求用邮箱加密码，或者用你的私人令牌。相比起来，SSH方式省心很多。
6. 高频报错排查与避坑现场
6.1 clone报错“git did not exit cleanly (code 128)”
这个报错经常出现在VS Code里执行clone或commit时，弹窗只显示这句话，不显示真正的错误原因。我的排查步骤固定这几步：
先到Git Bash里手动执行一遍同样的命令，看完整报错信息。比如复制VS Code的仓库地址，在Git Bash里执行：
bash复制git clone git@gitee.com:用户名/仓库名.git
如果手动跑是成功的，说明VS Code环境有问题，重启VS Code或重启电脑即可。如果手动跑也报错，看具体报错内容，常见原因有：
- 远端地址写错了，仓库不存在或没有权限。
- 公钥没配好，
ssh -T git@gitee.com都无法通过。 - 本地目录本身已经是个Git仓库，再执行clone到该目录会报错。
6.2 推送被拒绝：failed to push some refs
这个报错其实是最好解决的。它的意思是远程仓库里有本地没有的提交，通常是别人刚推了新代码，或者你在Gitee网页端直接改过文件。
解决方法就一句话：先拉取再推送。
bash复制git pull --rebase
--rebase会把你的本地提交暂时“挪到一边”，拉取远端最新代码，再把你的提交“重新放”到最新代码之上，历史记录更干净。如果不用--rebase直接用git pull，Git会自动创建一次合并提交，历史会多一个分叉合并点，不够清晰。
pull之后如果提示冲突，解决方式跟前面一致：手动改文件、git add、git commit或git rebase --continue、再git push。
6.3 认证明明配好了，为什么推送还要输账号密码
如果你用的是HTTPS地址连接远程仓库，SSH免密根本不生效，因为走的是另一套认证方式。解决方法是把远程地址改成SSH：
bash复制git remote set-url origin git@gitee.com:用户名/仓库名.git
如果你不想换SSH，也可以用Gitee的“私人令牌”来认证，到Gitee设置里生成一个私人令牌，推送时用户名填你的Gitee用户名，密码填这个令牌而非你的登录密码。
6.4 Git Bash中文文件名或路径乱码
Windows下中文显示乱码是常见问题，尤其是文件名里有中文时，Git默认会转成八进制转义序列显示。在Git Bash里执行：
bash复制git config --global core.quotepath false
设置完成后，中文文件名会正常显示，不再是一串\346\226\207之类的乱码。
6.5 Gitee Pages还能不能用来托管网页
如果你问“Gitee Pages是不是没有了”，我能说的是：这个功能近期开放状态有变动，之前能正常创建和访问的静态页面，现在有部分用户会遇到无法创建或无法访问的情况。如果你做个人博客或项目演示页，建议不要把Gitee Pages当作唯一方案。可以先把代码正常推到Gitee仓库做版本管理，页面托管问题再考虑部署到自己的云服务器或者其他静态站点托管服务上。
6.6 其他容易踩的小坑
- 新建Gitee仓库时开了“开源许可证”选项，但不知道选什么。简单说：想让别人随便用就选MIT，涉及专利保护就选Apache-2.0，要求衍生作品必须开源选GPL-3.0。
- Gitee创建Issue时验证码一直错。不用急着重试，等一两分钟再操作，连续失败会被暂时限制。
- 仓库是私有的，但发给同事链接让他们访问，对方打不开。这是正常的，私有仓库需要你在“仓库设置—成员管理”里把对方加进仓库，或者改成公开。
6.7 常用命令速查表
| 操作 | 命令 |
|---|---|
| 查看工作区状态 | git status |
| 暂存所有改动 | git add . |
| 提交改动 | git commit -m "说明" |
| 推送到远程 | git push |
| 拉取远程更新 | git pull --rebase |
| 查看提交历史 | git log --oneline |
| 撤销上次提交（保留改动） | git reset --soft HEAD~1 |
| 撤销提交并丢弃改动 | git reset --hard HEAD~1 |
| 生成反向提交 | git revert HEAD |
7. 进阶技巧：多账号切换和常用命令别名
7.1 一台电脑同时用Gitee和GitHub的SSH key
有时候你同事用Gitee，项目又发布在GitHub，甚至你在Gitee有多个账号，默认的id_rsa只对应一个账号。可以分拆成多对密钥，在~/.ssh/config文件里区分。
在Git Bash里执行：
bash复制cd ~/.ssh
ssh-keygen -t rsa -C "gitee" -f ~/.ssh/gitee_rsa
ssh-keygen -t rsa -C "github" -f ~/.ssh/github_rsa
然后编辑~/.ssh/config：
text复制Host gitee.com
HostName gitee.com
User git
IdentityFile ~/.ssh/gitee_rsa
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/github_rsa
这样Git连接不同的域名时会自动使用对应的私钥，互不干扰。具体的公钥分别添加到对应的Gitee和GitHub后台。
7.2 Git别名：让常用命令缩短一半
在Git Bash里执行：
bash复制git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.lg "log --oneline --graph --all -10"
配置完以后，git st等于git status，git co等于git checkout，git lg直接查看最近10条提交历史带分支图。用习惯了之后，比完整命令高效很多。这些配置写在~/.gitconfig里，换电脑时可以直接复制这个文件。
7.3 我踩过的最印象深刻的坑
有一次我推代码时莫名其妙报“Repository not found”，SSH测试却提示认证成功，后来检查发现是git remote -v显示的仓库地址里用户名少了一个字母，估计是当初建仓库时复制地址前手动改了仓库名导致不一致。所以大家切远程地址后，先执行：
bash复制git remote -v
确认显示的是git@gitee.com:正确的用户名/正确的仓库名.git，再执行推送。
还有一次遇到的问题更隐蔽：本来一切正常，突然所有推送都要求输入账号密码。排查了很久发现是某次操作时手滑执行了git config --global credential.helper，把凭据模式改掉了。如果你哪天遇到“以前不用输密码，现在突然要输”，先执行git config --global -l看一眼配置有没有被改动。
8. 写在最后的个人经验
我的建议是，刚接触Git不要试图一下记住所有命令，先把最基础的一条路走通：git init建仓库，git add暂存，git commit提交，git push推送到Gitee。这条链路每天都会用到，跑通了再慢慢扩展分支、回滚、rebase这些高级功能。等形成了肌肉记忆，你会发现版本控制这件事根本不难，反而会成为你开发流程里最稳定可靠的一环。