1. 为什么我强烈建议你用 VSCode 的图形界面来操作 Git
先说实话：Git 本身是个命令行工具，网上绝大多数教程也都在教你敲命令。但我带过不少新人，发现一个特别普遍的现象——命令记不住，顺序搞混，报错看不懂。一上来就硬啃命令行，很容易在最初两周就把热情消耗光。
我自己也是从命令行时代过来的，git status、git add、git commit、git push 这几个命令敲了大半年才真正理解它们之间的关系。后来有一次切换到 VSCode 的源代码管理面板，突然发现之前怎么都理不清的"工作区、暂存区、本地仓库、远程仓库"这几个概念，在图形界面上看得明明白白——每个文件的状态有图标标识，改动有高亮对比，提交按钮就摆在眼前。从那以后我就养成了"日常操作用界面，复杂操作用命令行"的习惯，效率反倒比纯命令行高不少。
VSCode 内置了完整的 Git 支持，不需要装额外的插件就能完成仓库初始化、暂存、提交、推送、拉取、分支切换、合并、冲突解决这些日常高频操作。GitLens 这类增强插件则能进一步补足历史查看、代码责任人追溯等能力。对于新手，这是一条平滑的学习曲线；对于老手，可视化 diff 和冲突解决界面也远比命令行直观。
这篇文章会从零开始，覆盖 VSCode 和 Git 的安装、初始化配置、SSH 密钥设置，再到用图形界面完成一次完整的代码提交和推送流程，最后整理我在实际使用中遇到的各种问题和对应的排查方案。所有步骤我在 Windows 和 macOS 上都实测过，有系统差异的地方会单独标注。你只需要跟着一步步做，就能在半天内把环境搭好、流程跑通。
2. 环境准备：从零装好 VSCode 和 Git
2.1 VSCode 官方下载与安装步骤
先说下载渠道，这是很多人第一步就走错的地方。VSCode 的官网是 code.visualstudio.com，注意不要跑到各种"软件下载站"去下载。那些站点经常捆绑垃圾软件、改主页，甚至给你塞一个来路不明的修改版。我见过好几个同事电脑上的"VSCode"其实是第三方打包的，界面长得一样，但装完一堆全家桶，还经常崩溃。认准官网，这是第一条铁律。
进入官网后，页面会自动识别你的操作系统，显示对应的下载按钮。Windows 用户下载 User Installer 64 bit 版本就可以，macOS 用户选择 Apple Silicon 还是 Intel 版本，取决于你的芯片型号。下载完成后双击安装包，安装路径默认在用户目录下，不需要管理员权限，这点很省心。
安装过程中有两个选项需要注意。第一个是"添加到 PATH"，默认是勾选的，建议保留。这个选项会让命令行里能直接输入 code 命令打开 VSCode，后续配合终端使用非常方便。第二个是"在文件资源管理器上下文菜单中打开"和"添加到'打开方式'列表"，我也建议勾上，这样以后在文件夹上右键就能直接"通过 Code 打开"，省去每次打开 VSCode 再拖文件夹的麻烦。
启动之后看到英文界面是正常的，中文配置放到后面专门讲。这时候你可以先按 Ctrl + ` 呼出内置终端，输入 code --version 检查一下安装是否正常。如果提示 command not found，说明 PATH 没配好，重启一次系统或者手动把 VSCode 的 bin 目录加到系统环境变量里就行。
2.2 Git 的下载安装与 Windows 专属注意事项
Git 的官方下载地址是 git-scm.com，官网会自动识别操作系统并提供下载链接。Windows 版本的安装包是一个 exe，直接双击运行。不过 Git 的安装向导选项比较多，很多人一路狂点下一步，结果后面用起来各种不对劲。我这里把几个关键选项拎出来说清楚。
- 选择默认编辑器：默认是 Vim。如果你不熟悉 Vim，建议在这里改成 VSCode。不然以后在命令行里执行 git commit 弹出一个 Vim 编辑器，你可能会被卡在里面不知道怎么退出。这个编辑器选项在安装完成后也可以通过 git config --global core.editor "code --wait" 修改。
- 调整 PATH 环境变量：保持默认的 "Git from the command line and also from 3rd-party software" 就行。这个选项会让 Git 的 bash 和命令工具都能在 Windows 终端里直接使用。
- 配置行结束符转换：默认选项 "Checkout Windows-style, commit Unix-style line endings" 适合绝大多数人，这个我们后面讲 LF/CRLF 的时候再展开。
- 使用 MinTTY 还是 Windows 自带的控制台窗口：默认的 MinTTY 体验更好，支持颜色高亮，保持默认即可。
安装完成后，在任意文件夹里右键，如果能看到 "Git Bash Here" 和 "Git GUI Here" 两个选项，说明安装成功了。点开 Git Bash，输入 git --version，能看到类似 git version 2.4x.x.windows.1 的输出，就是正常的。
macOS 用户相对简单，官网下载 pkg 安装包一路下一步即可，或者通过 Homebrew 执行 brew install git 也行。macOS 首次运行 git 会触发 Xcode Command Line Tools 的安装提示，那个是 Apple 官方的，可以放心装。
2.3 安装完成后的基础验证
环境装好之后，建议做两个简单的验证，避免后面用的时候才发现问题。
第一个验证是确认 VSCode 能识别 Git。打开 VSCode，按 Ctrl + Shift + X 打开扩展面板，搜索 "Git"，你会看到内置的 Git 扩展是已安装状态。左侧活动栏如果出现了源代码管理图标（一个带分支的圆圈图形），说明 VSCode 已经检测到了 Git。如果图标没出来，大多数情况是因为 Git 没装好或者没加入 PATH。
第二个验证是确认 Git Bash 能正常启动。Windows 用户在开始菜单里找到 Git Bash，打开后执行 git config --list，如果能看到一堆配置项（或者什么提示都没有），说明 Git 工作正常。如果提示 git: command not found，大概率是 PATH 配置有问题，可以检查一下系统环境变量里有没有 Git 的 cmd 目录。
到这一步，你的电脑就已经具备了完整的开发基础环境。接下来我们开始配置和定制 VSCode。
3. 首次启动：汉化、工作区与必装插件
3.1 界面语言切换成中文
很多新手看到满屏英文就头大，其实汉化非常简单。打开 VSCode，按 Ctrl + Shift + X 打开扩展市场，在搜索框输入 Chinese，找到 "Chinese (Simplified) (简体中文) Language Pack for Visual Studio Code" 这个扩展。注意认准发布者是 Microsoft 官方，因为市场上还有其他第三方汉化包，质量参差不齐。
点击 Install 安装后，右下角会弹出提示框，让你 Restart 重启 VSCode。重启后整个界面就变成中文了。如果没弹出重启提示，也可以按 Ctrl + Shift + P 打开命令面板，输入 Configure Display Language，选择 zh-cn 再重启。
这里多说一句：对于有一定基础的朋友，我不建议一上来就汉化。VSCode 的菜单术语跟 Git 的常用英文术语是对应的，比如 Stage Changes（暂存更改）、Commit（提交）、Pull（拉取）、Push（推送）。直接用英文界面，能帮助你把界面操作和命令行术语对上号，以后再切到命令行不会懵。但如果你确实看着英文费劲，汉化没有任何问题，后面讲到操作时我也会标注对应的英文术语，方便你对照。
3.2 我每次重装 VSCode 都会装的插件
插件是 VSCode 的灵魂，但很多人一上来就装几十个插件，搞得编辑器又慢又乱。我自己的原则是：装必要的，不装花哨的。以下这几个是我每次重装环境都会第一时间装的，覆盖了从代码编辑到 Git 操作的核心需求。
- GitLens：增强 Git 功能最强的插件。它能高亮当前行最后一次提交的人和时间，点击就能看到该文件完整的提交历史，还内置了可视化的分支关系图。我用它最多的是 CodeLens 功能——在每一段代码上方直接显示最近一次提交信息和作者，代码 review 的时候特别有用。
- Prettier - Code formatter：代码格式化工具。保存时自动格式化代码，统一团队的代码风格。装完记得在设置里把 "Editor: Format On Save" 打开，并把 Prettier 设置为默认格式化器。
- ESLint：JavaScript/TypeScript 的静态检查工具。前端开发基本必装，能在你写代码的同时标出潜在问题。如果你主要做 Python，对应安装 Pylance 或者 flake8。
- Live Server：前端开发实时预览工具。右键 HTML 文件选择 "Open with Live Server"，浏览器会自动打开页面并且每次保存自动刷新，写静态页面调试非常方便。
- Bracket Pair Colorizer 的替代方案：现在 VSCode 自带括号高亮配色，不需要额外装插件。同样，内置的 Git 支持已经很强，也不需要装额外的 Git 插件，GitLens 一个就够。
插件的安装方式都一样：Ctrl + Shift + X 打开扩展面板，搜索名称，点击 Install。装完不需要重启，VSCode 的热加载机制会立即生效。
还有一个容易被忽略的功能：扩展面板右上角的筛选按钮，可以按 "已在架" 或者 "内置" 来查看已安装的插件。电脑配置一般的话，建议定期审视插件列表，把不用的卸载掉。我曾经装过一个主题插件导致编辑大文件时卡顿，排查了半天才找到元凶——插件真的不是越多越好。
3.3 工作区与项目文件夹的底层逻辑
刚开始用 VSCode 的人，经常混淆"文件"和"文件夹"的概念。VSCode 的基本单位是文件夹，也就是一个项目目录。你打开一个文件夹后，VSCode 会把它作为一个工作区进行管理，左侧资源管理器显示的是这个文件夹内的所有文件，Git 仓库也随之关联到这个目录层级。
我推荐的工作方式是：在电脑上建一个专门的代码目录，比如 D:\Projects，然后把每个项目分别放进独立的子文件夹，比如 D:\Projects\my-blog、D:\Projects\demo-app。每次开发时，直接 File > Open Folder 选择对应的项目文件夹。
这个习惯很重要，因为它直接影响了 Git 仓库的组织方式。一个项目文件夹就对应一个 Git 仓库，仓库根目录通常会有一个 .git 隐藏文件夹存放所有版本记录。如果你把文件散落在桌面、下载目录各处，以后管理和备份都是灾难。
VSCode 还有一个"多根工作区"的概念，可以把多个文件夹聚合到一个工作区里，方便同时编辑。但对 Git 操作来说，我建议还是一个窗口对应一个仓库，避免在两个仓库之间切换时搞混。我在刚用 VSCode 时犯过一个错误：开了多根工作区，结果源代码管理面板显示的提交按钮对应的是错误仓库，差点把代码推错地方。从那以后我就老老实实一个窗口一个仓库。
3.4 顺手把自动保存和常用设置配好
装完插件之后，建议花几分钟调整几个基础设置，这些设置能让日常使用顺畅很多。
按 Ctrl + , 打开设置面板，建议开启：
- Files: Auto Save设置为 afterDelay，默认是 off。开启后文件在停止输入几秒后自动保存，配合 Git 的实时状态刷新，能确保你提交的时候内容是最新的。不过注意自动保存不保证立即写入磁盘，有强迫症的话可以关掉，用 Ctrl + S 手动保存。
- Editor: Font Size设为 14 或 16，默认的 12 对很多人的屏幕来说偏小。
- Editor: Tab Size保持默认 4 还是改成 2，取决于团队规范，Python 建议 4，JavaScript/TypeScript 建议 2。
- Files: Exclude可以配置资源管理器隐藏文件，比如把 node_modules、dist 这类不常动的目录隐藏掉，让文件列表更清爽。不过这不影响 Git 操作，Git 是否跟踪文件由 .gitignore 决定。
这些设置属于个人习惯，不需要照搬。我的核心建议是打开自动保存，其他的按你舒服的方式来。
4. Git 身份配置与 SSH 密钥：一次性搞定，后面不再烦
4.1 告诉 Git 你是谁：user.name 和 user.email
Git 每次提交都会记录作者信息，这个信息来自 Git 的全局配置。如果你没有配置，第一次提交时会报错：Please tell me who you are。
配置方法很简单，打开 Git Bash（Windows）或者终端（macOS），执行以下两条命令：
git config --global user.name "你的名字" git config --global user.email "你的邮箱@example.com"注意两个细节。第一，user.name 建议用拼音或者英文昵称，尽量避免中文，因为某些老式工具链对中文用户名的支持不太好。第二，user.email 必须和你托管平台（GitHub、Gitee 等）注册的邮箱一致。这不是强制要求，但只有邮箱一致，你的提交才能正确关联到对应的账号，贡献度统计也会正确显示。
配置完成之后，可以用 git config --list 检查所有配置项。如果发现配置错了，重新执行 git config --global 加同样的参数覆盖即可。如果想查看单个配置，执行 git config user.name 和 git config user.email 即可。
这里还有个容易忽略的点：git config --global 设置的是全局配置，作用于这台电脑上所有 Git 仓库。如果你同时给公司和个人项目使用同一台电脑，而两边的提交邮箱不一样，那就需要用仓库级别的配置覆盖。在特定项目目录下执行不带 --global 的 git config user.name 和 git config user.email，就能单独设置这个仓库的身份。
4.2 生成 SSH 密钥并配置到 GitHub / Gitee
代码托管平台支持 HTTPS 和 SSH 两种方式来访问远程仓库。对新手来说，HTTPS 更简单，但每次推送都要输入账号密码或者 Token，非常烦人。SSH 方式配置好后，一劳永逸，所以我强烈建议直接上 SSH。
生成 SSH 密钥的步骤在 Git Bash 里执行：
ssh-keygen -t ed25519 -C "你的邮箱@example.com"如果系统提示 ed25519 不支持，可以改用 rsa：
ssh-keygen -t rsa -b 4096 -C "你的邮箱@example.com"命令执行后，它会问你要把密钥保存在哪里，直接回车使用默认路径（一般是 ~/.ssh/id_ed25519）。然后会要求设置一个 passphrase（密码短语），这一步可以留空直接回车，也可以设置一个。设置的话，每次使用私钥都要输入一次密码，安全性高一些；不设置的话，方便，但私钥泄露就意味着仓库被接管。我个人建议设置，虽然每次连接会多一步输密码，但养成安全习惯总没错。
密钥生成后，需要把公钥添加到托管平台。先查看公钥内容：
cat ~/.ssh/id_ed25519.pub把输出的以 ssh-ed25519 开头、邮箱结尾的一整行内容复制。然后登录 GitHub，打开 Settings > SSH and GPG keys > New SSH key，粘贴保存。Gitee 的路径类似：设置 > 安全设置 > SSH 公钥，粘贴保存。
4.3 验证连接与常见认证报错
配置完成后，执行下面的命令验证连接是否成功：
ssh -T git@github.com如果是 Gitee：
ssh -T git@gitee.com第一次连接会提示确认指纹，输入 yes 回车即可。如果输出类似 Hi username! You've successfully authenticated 的提示，恭喜你，SSH 配置完成。
我在实际使用中遇到过的认证问题主要有三类，这里一并说明。
第一类是 Permission denied (publickey)。这种报错说明 Git 没有找到你的私钥，或者公钥没有正确添加到托管平台。排查思路：先用 ssh-add -l 查看当前私钥加载情况，没有的话执行 ssh-add ~/.ssh/id_ed25519；再确认公钥确实已经粘贴到平台，注意粘贴时要复制完整，不要漏掉结尾邮箱。
第二类是 Host key verification failed。这说明本机的主机密钥记录和远程服务器对不上，常见于服务器重置或换了 IP。解决方法是删除 known_hosts 里对应记录，执行 ssh-keygen -R github.com，然后重新连接。
第三类是连接超时。这种情况大多数是网络问题，可以先试试 ping github.com 或者直接浏览器访问 GitHub 看是否正常。如果浏览器都打不开，那就是网络本身的问题，等网络恢复再试就行。
5. 用 VSCode 完成 Git 全流程可视化操作
5.1 初始化仓库与第一次提交
现在环境已经准备好了，我们开始实战。这里我用一个场景来演示：你新建了一个文件夹 D:\Projects\my-project，里面放了几个代码文件，现在想用 Git 管理起来。
在 VSCode 中打开这个文件夹，点击左侧活动栏的源代码管理图标（圆形分支符号），面板里会提示"此文件夹当前未启用 Git 存储库"之类的话，旁边通常有 Initialize Repository 按钮。点击它，或者按 Ctrl + Shift + P 输入 Git: Initialize Repository 并回车，就完成了仓库初始化。
初始化之后，你会看到源代码管理面板里列出所有未跟踪的文件，文件名旁边有 U 标记，代表 Untracked（未被 Git 跟踪）。鼠标悬停在文件上会出现加号图标，点击就把文件暂存了，对应命令行里的 git add。暂存后文件前面的标记变成 A（Added）。
接下来写提交信息。在源代码管理面板顶部有一个"消息"输入框，输入你的提交说明，比如 "初始化项目"，然后点 Commit 按钮，或者按 Ctrl + Enter 完成提交。此时你的代码已经保存到本地仓库了，对应命令行里的 git commit -m "初始化项目"。
这里我补充一个从命令行时代就保留下来的习惯：提交信息不要写"更新"、"修改"这种废话，要写清楚"做了什么"，比如"修复登录接口空指针异常"、"新增商品列表分页功能"。这样以后翻提交记录时，每一行都是可读的，而不是满屏的 update。VSCode 还支持在消息框里换行写多行提交信息，第一行写标题，空一行后写正文，这个格式对应了 Git 提交信息的通用规范。
5.2 推送到远程仓库：搭配 GitHub 和 Gitee
本地仓库建好了，现在把代码推到远程。先在 GitHub 或 Gitee 上新建一个空仓库，如果创建时让你选择是否添加 README 或 .gitignore，建议都选"无"，保持空仓库，避免和本地仓库产生冲突合并的问题。
在 VSCode 源代码管理面板右上角，点击"..."菜单，选择推送（Push）。如果是第一次推送，VSCode 会要求你添加远程仓库地址，在弹出的输入框里填上远程仓库的 SSH 地址，形如 git@github.com:username/repo.git。
推送时 VSCode 可能会提示你没有上游分支。在命令行时代，第一次推送需要执行 git push -u origin main 来建立本地分支和远程分支的关联。VSCode 里图形化操作时，直接选择"发布分支"或"推送"即可，它会自动帮你做关联。推送成功后会弹出一个提示，并在状态栏同步显示当前分支与远程的同步状态。
这里有个新手容易踩的坑：推不上去，报错提示"当前分支没有上游分支"（upstream branch）。解决办法就是在命令面板里执行 Git: Push 之后再执行 Git: 检查，或者直接用命令行补一条 git push -u origin main。VSCode 的图形化界面有时候不会自动帮你关联上游分支，遇到这提示别慌，按上面的方法处理就行。
5.3 拉取与同步：每天开工先 sync
代码推送上去了，团队协作时每天开工第一件事就是拉取最新的代码。VSCode 状态栏左下角有两个圆形箭头图标，分别是"同步"和"拉取"。点击同步，VSCode 会先拉取远程变更，再把本地提交推上去，一次完成双向同步。
我在实际开发中的做法是：开工前先点一次同步，确保本地代码是最新的；每次提交前也点一次同步，把同事的改动拉下来，避免集中推上去产生大量冲突。
这里要重点提醒：如果你的本地有未提交的改动，直接拉取远程代码，有可能会把别人的改动合进来的时候产生冲突。VSCode 的处理方式是：如果拉取时你的工作区有冲突文件，它会在源代码管理面板中列出冲突文件，让你逐个解决。这个我们放到后面冲突处理的部分详细讲。
此外，VSCode 的源代码管理面板右上角有个刷新按钮，点击会重新扫描文件状态。有时候你改了文件但状态没更新，点一下刷新就好。GitLens 插件还提供了一个实时检查组件的功能，在状态栏显示当前分支落后或者领先远程多少个提交，用起来特别直观。
5.4 分支管理：新建、切换与合并
分支是 Git 最强大的功能，也是最容易让新手迷惑的部分。用生活化的方式解释：主分支（main）就像一条稳定的主干道，你修新功能时不要直接在主干道上动工，而是开一条辅道（分支），在辅道上折腾，等测试没问题了再并回主干道。
在 VSCode 中，点击左下角当前分支名称（默认显示 main 或者 master），会弹出分支管理面板。在这里可以执行新建分支、切换分支、删除分支等操作。新建分支的方法是：在弹出的面板顶部输入框里输入新分支名，选择"创建新分支"并回车即可。VSCode 会同时完成分支创建和切换，相当于命令行里的 git checkout -b。
分支合并的操作也很直观：先切换到要接收更改的目标分支（比如 main），然后在命令面板里输入 Git: Merge Branch，选择要合并进来的分支（比如 feature/login），确认即可。如果合并没有冲突，VSCode 会直接完成合并，源代码管理面板里会显示合并产生的提交。
我使用分支的实际建议：即使是个人开发，也不要长期在 main 分支上直接开发。创建一个 dev 开发分支，日常提交都在 dev 上，功能稳定后再合并到 main。这能让你在出问题的时候可以随时回滚到上一个稳定版本，而不需要把所有代码改动一起回滚。在 VSCode 里操作分支极其轻量，养成这个习惯完全不需要额外成本。
5.5 冲突处理：可视化解决合并冲突
合并冲突是 Git 使用中最让人头疼的事，但 VSCode 的可视化解决界面做得相当好，可以说是新手的救星。
当合并出现冲突时，VSCode 源代码管理面板会列出冲突文件，打开这些文件，编辑器里会显示醒目的冲突区块，颜色编码一目了然。冲突区块的上半部分是当前分支的代码（Current Change），下半部分是传入分支的代码（Incoming Change）。
在冲突区块上方有一排操作按钮，包括：
- Accept Current Change：保留当前分支的版本
- Accept Incoming Change：采用传入分支的版本
- Accept Both Changes：两者都保留
- Compare Changes：并排对比两个版本
实际操作中，"Accept Both Changes" 用得比较少，因为两个版本直接拼接往往会导致代码逻辑重复。我一般的做法是：先看 Current 和 Incoming 两个版本的区别，如果只是同一位置的不同写法，就根据业务语义选一个；如果是两个人改了不同位置，就手动编辑冲突区域，把需要的代码保留下来，把冲突标记（<<<<<<<、=======、>>>>>>> 这三行）删掉。
解决完全部冲突文件之后，源代码管理面板会自动把文件标记为已解决（M 标记，Modified），输入提交信息，点击 Commit，合并就完成了。
这里我必须多说一句：解决冲突一定要看上下文，不要盲目选择"保留一侧"。我就曾经偷懒，在两个人同时改了同名函数的情况下直接接受了当前分支的版本，结果功能上线后找不到代码，查了半天才发现函数被别人改名了。冲突解决是 Git 操作中最需要谨慎的地方，宁可慢一点，也要把冲突区域的前后代码都读一遍再决定。
5.6 撤销与修正：后悔药怎么吃
Git 的好处在于几乎所有的误操作都有挽回余地。VSCode 源代码管理面板的"..."菜单里提供了几个常用的撤销选项：
- 放弃更改（Discard Changes）：丢弃工作区的未提交修改，恢复到上一次提交的状态。这个操作对应命令行里的 git checkout -- 或 git restore。注意：这个操作不可撤销，执行前最好确认一下这个文件的所有修改都不需要了。
- 取消暂存（Unstage）：如果你误暂存了文件，从源代码管理面板点击该文件前面的减号图标，就能取消暂存，对应 git reset HEAD 。
- 回滚上次提交（Undo Last Commit）：对应命令行的 git reset --soft HEAD~1，保留更改但移除提交记录。这个操作适合刚提交完发现漏了文件或者提交信息写错的情况。在命令面板中搜索 Git: Undo Last Commit 即可执行。
和提交信息修改相关的还有 git commit --amend，这个命令可以修改上一次的提交信息或者追加文件到上一次提交。在 VSCode 中没有直接的图形化按钮，但可以在命令面板中输入 Git: Commit (Amend) 来执行。需要注意的是，amend 会改变提交的 hash，如果这个提交已经被推送到远程并且别人已经拉过去了，不建议使用 amend，否则会产生分叉历史。安全的使用场景是：提交还在本地，没有被推送过。
6. 常见问题与排查技巧实录
6.1 文件状态不刷新、图标不显示
这个问题特别常见，很多人第一反应是 VSCode 坏了，其实大部分情况只是缓存问题。如果你改了文件但源代码管理面板状态一直是旧的，先点面板右上角的刷新按钮；如果还不行，按 Ctrl + Shift + P 执行 Developer: Reload Window 重载窗口。
还有一种情况是文件图标不显示，比如改了文件后字母标记没变。这个一般是 VSCode 的文件监视器出了问题。在 Linux 或 WSL 环境里，默认的文件监视上限可能不够，可以在系统里调高 fs.inotify.max_user_watches 的值。Windows 和 macOS 基本不用管，直接重载窗口就能解决。
6.2 "Please tell me who you are" 以及身份配置问题
这个报错是新手最常遇到的，原因就是没有配置 user.name 和 user.email。解决办法在 4.1 里已经写了。但我还遇到过一种情况：全局配置明明是好的，单个仓库里却还是报这个错。这种一般是这个仓库有自己的局部配置，而且局部配置里的 user.name 是空的。检查方法是在项目目录执行 git config --list，看看输出里有没有 user.name 和 user.email；如果局部配置覆盖了全局配置但没有值，就重新在项目目录下配置一次即可。
6.3 认证失败：HTTPS Token 与 SSH 密钥问题
使用 HTTPS 方式克隆仓库的人，推送时经常会遇到 Authentication failed 或者要求输入用户名密码，但输入对了还是报错。这是因为 GitHub 和 Gitee 早在几年前就取消了密码推送，现在必须使用 Personal Access Token 作为密码。在 GitHub 的 Settings > Developer settings > Personal access tokens 里生成一个 token，勾选 repo 权限，然后复制这个 token 作为密码粘贴即可。
如果你之前在命令行里输入过错误的密码或者 Token，Windows 的凭据管理器会记住这个错误值，导致后面每次都失败。这时候需要打开控制面板 > 用户账户 > 凭据管理器，找到 git:https://github.com 这一项，把它删掉，下次推送时重新输入正确的 Token。
SSH 方式的认证报错在 4.3 已经详细讲过，这里不再重复。核心思路就是：先确认私钥是否加载（ssh-add -l），再确认公钥是否添加，最后用 ssh -T git@github.com 做连通性测试。
6.4 中文乱码与提交信息编码问题
Windows 上遇到中文乱码的场景主要有两个：一是 Git Bash 里 ls 显示中文文件名为转义字符，二是 VSCode 里提交信息或者 diff 内容里的中文乱码。
第一个问题，执行 git config --global core.quotepath false 可以解决。这个配置让 Git 直接显示原始中文字符，而不是用八进制转义序列 (\346\226\207) 表示。
第二个问题，通常和 Git 的字符编码相关。Windows 默认使用 GBK 编码，而 Git 和大部分代码文件默认是 UTF-8。解决办法是把 Git 的默认提交信息编码改为 UTF-8：git config --global i18n.commitencoding utf-8 和 git config --global i18n.logoutputencoding utf-8。然后在 Git Bash 的属性里把字符集设置为 UTF-8。VSCode 本身默认 UTF-8 处理文件，所以 VSCode 里看到乱码往往是文件本身就是 GBK 编码，需要点击右下角的编码信息，选择"通过编码重新打开"，再选择 GBK 或 GB2312 就可以显示正常了。
6.5 LF/CRLF 行结束符警告与转换
在 Windows 上使用 Git，经常会在提交或拉取时看到这样的警告：warning: LF will be replaced by CRLF。这个警告来自 Git 的行结束符自动转换机制。Windows 的文本换行用 CRLF（回车加换行），而 Linux 和 macOS 用 LF（仅换行）。Git 为了跨平台协作，默认在检出代码时转换为 CRLF，提交时转换为 LF。
如果你是自己一个人开发，不想被这个警告打扰，可以执行 git config --global core.autocrlf false，关闭自动转换。但如果你的团队是跨平台协作的，我建议保持默认设置。在 VSCode 里编辑时，右下角状态栏会显示当前文件的换行符类型（CRLF 或 LF），如果混用了需要用哪个都行，但提交前最好统一。配置文件类（.gitattributes）可以用来自定义每个文件类型的行结束符规则，这是团队协作时的最佳实践，不过对于刚上手的朋友来说，保持默认 + 忽略警告就够了。
6.6 忘记了 Git 密码、密钥丢失怎么办
最后分享一个我踩过的大坑：有一次换了电脑，发现旧电脑的 SSH 私钥没备份，结果所有配置了公钥的仓库全都连不上了。解决办法只能是重新生成密钥对、把新公钥重新添加到各个托管平台的账号里。旧私钥已经丢失，按理说应该把平台上旧公钥删掉，否则这个公钥就变成了一个永久的后门。
这件事给我的教训是：SSH 私钥（id_ed25519 这个没有任何扩展名的文件）是极其重要的文件，它相当于你访问所有代码仓库的身份证。建议在生成密钥后立刻备份一份到密码管理器，同时把公钥添加到托管平台后，先在一台设备上确认能正常连接再继续下一步。如果你发现有设备丢失或不再使用，记得第一时间去托管平台删除对应的公钥。
7. 最后补充：我平时使用 VSCode + Git 的几个习惯
写了这么多，正文其实已经讲完了。最后再分享几个我在日常工作中养成的习惯，谈不上什么标准答案，但确实帮我省了不少事。
第一个习惯是每天开工前先拉取，收工前一定推送。很多人喜欢一口气写很多代码再推，结果一推就是几十个提交，中途要是插进来同事的改动，合并冲突能把人搞疯。我现在的节奏是：小步快跑，每次完成一个独立的小功能就提交一次推送一次，提交信息写清楚。这样就算哪里写错了，回滚的代价也很小。
第二个习惯是善用 .gitignore 文件。项目初始化时就把 node_modules、dist、.env 这些目录和文件加进去，避免把依赖包和敏感配置提交到仓库。VSCode 的源代码管理面板会直接忽略被 .gitignore 排除的文件，列表看起来干净很多。如果你现在还没建 .gitignore，可以在项目根目录新建一个文件，里面写上常见的忽略规则。GitHub 官方还提供了各种语言的 .gitignore 模板，直接搜来用就行。
第三个习惯是把命令面板当成随身工具。VSCode 里很多 Git 操作可以在图形界面完成，但是命令面板（Ctrl + Shift + P）里输入 Git: 能列出所有可用的 Git 操作，包括很多图形界面没有入口的，比如 amend、stash、cherry-pick。学会用命令面板，你会发现 VSCode 的 Git 能力远比你看到的按钮多。即使你以后想转回命令行，这个概念也一样——你只需要知道 Git 能做什么，具体的实现方式反而不那么重要。
写到这里，整条"装环境、配身份、连远程、日常操作、处理冲突、排故障"的流程就完整了。我最早学 Git 的时候，被命令行折腾得怀疑人生，后来换了可视化操作才真正把流程跑通。现在我的电脑上开着 VSCode 的频率远超纯终端，但遇到复杂的变基操作或者需要精细控制的时候，还是会切回命令行。这两种方式不冲突，它们是同一个工具在不同场景下的两种形态。希望这篇指南能帮你把最基础的那 90% 用顺，剩下的复杂场景，等你熟悉了再慢慢探索也不迟。
