企业官网建设流程全解析

我入行前端那几年，最怕的不是需求变更，而是同事发来一句“代码我 push 上去了，你拉下来看看”。这句话听上去只是 Git 操作，但在 Windows 上，如果 Git 没有装对，后面跟着的往往是：分支不识别、换行符全乱、中文文件名字符集爆炸、clone 到一半证书报错。所以我才决定把 2026 前端开发 Windows 安装 Git 配置指南写出来，尤其针对我这次在 Windows 11 上装的 Git for Windows 2.53.0(2) x64，把“从下载到配置完成”这条路完整走一遍，同时把每个安装选项背后的逻辑讲清楚。

什么人适合照着走一遍？刚入行的前端新人、从 Mac 切到 Windows 的开发者、以及被公司 Windows 笔记本折腾过的老手。这篇内容能帮你完成 Git 本体安装、基础身份配置、SSH 免密登录、VS Code 联动，还有一堆我在实际项目里踩过的坑的排查方法。不管你是第一次装 Git，还是已经装在电脑上但总觉得哪里别扭，按这个流程整理一遍，后面会省心很多。

1. 项目概述：前端开发在 Windows 上配 Git，真不是双击下一步那么简单

1.1 前端工作流里 Git 的位置：不只是代码仓库

很多人以为 Git 就是个“保存代码版本的工具”，其实对前端来说，Git 是协作、发布、回滚、Code Review 和自动化部署的地基。现在稍微正规一点的前端项目，基本都是多人维护、多环境部署，代码要经过 feature 分支开发、MR/PR 评审、CI 自动构建，最后才能在测试机或生产环境上线。这一整条链路里，只要 Git 配置有任何一个环节不对劲，后面全乱。

在 Windows 上这个问题的复杂度会被放大。因为 Git 最初是在 Linux/macOS 生态里长大的，到了 Windows 上，路径分隔符、换行符、文件系统大小写、终端编码这些细节全都要重新适配。安装 Git 时如果一路无脑 Next，可能也能用，但遇到团队协作时往往会出现“我本地没问题，为什么 CI 挂了”“我改了一行，diff 怎么满屏红”这种让人血压飙升的情况。所以这篇文章表面是在讲安装，实际上是在帮你把 Windows 上 Git 的环境问题一次性清干净。

1.2 这次的版本：Git for Windows 2.53.0(2) x64 是什么

Git 官方在 2026 年仍然保持滚动更新，Windows 用户最常用的发行版叫 Git for Windows，也就是 git-scm.com 首页推荐下载的那个安装包。它不只带了 Git 本体，还额外打包了 Git Bash、Git GUI、Git LFS、Git Credential Manager 这些配套工具，装完基本不需要再单独折腾底层依赖。

版本号里的 2.53.0 是 Git 主版本号，括号里的 (2) 表示这个版本号的第二次修订构建，x64 表示这是 64 位版。我这次拿到的安装包大致叫 Git-2.53.0-2-64-bit.exe，大约五六十 MB，安装过程还是和之前几个版本保持了同一套向导风格。如果你之前在 2.4x、2.5x 版本上踩过坑，这篇指南里的选项说明同样适用，因为 Git for Windows 的安装流程已经相当稳定，变的通常只是内部功能和安全策略。

1.3 这篇指南覆盖的完整流程

我会按我实际安装的顺序来写：安装前需要做的两个决策、安装向导里每一页怎么选、安装完成后必须先做的身份配置、SSH 免密登录、VS Code 联动，以及前端项目里最常见的 Git 问题排查。中间会穿插一些“为什么这样做”的解释，因为很多时候你知道要勾哪个选项，但不知道不勾会出什么问题，一旦环境变了就不知道怎么应对。

建议你拿到安装包后先别急着双击，把第二部分的准备事项看完，磨刀不误砍柴工。如果你已经装过 Git，也可以直接跳到第四部分和第六部分，看看有没有漏掉的配置项。

2. 安装前的准备：选对安装包，少踩一半坑

2.1 确认系统架构：x64 还是 ARM64

第一件事不是下载，而是确认你的 Windows 是哪一种 CPU 架构。绝大多数公司发的办公笔记本和台式机都是 x64，也就是 AMD64 或 Intel 64，这种情况下直接选 x64 安装包没问题。但最近两三年，Windows ARM 设备明显变多了，像一些搭载骁龙处理器的轻薄本，如果误装了 x64 版，虽然 Windows 有模拟层可能也能跑，但性能和兼容性都不如原生 ARM64 版。

怎么看自己的系统架构？Win+R 运行msinfo32，在“系统类型”一栏能看到“基于 x64 的电脑”还是“基于 ARM 的电脑”。也可以右键“此电脑”选“属性”，查看“系统类型”。这一步特别适合刚拿到新电脑时做，别等到装完了才发现装错架构，卸载重装浪费十分钟不说，还可能把 PATH 环境变量搞乱。

2.2 下载安装包：命名规则和官方渠道

下载渠道我只认准 git-scm.com/download/win，进入页面后它会自动识别你的 Windows 版本并推荐 64 位安装包。页面上通常给两类文件：一类是Git-2.53.0-2-64-bit.exe这种 Standalone Installer，也就是最常见的安装向导包；另一类是PortableGit-2.53.0-2-64-bit.7z.exe，属于便携版，不需要安装，适合放在 U 盘里临时用。

我建议普通前端开发者直接选安装版，因为 Git for Windows 安装版会自动配好 PATH、右键菜单、文件关联这些基础项，省得手动折腾。便携版适合运维或需要多版本切换的场景，日常开发没必要。另外，千万不要去第三方软件站下载“Git 中文版”“Git 绿色版”，那些镜像站很容易捆绑全家桶，甚至安装包里被人塞了改过的二进制文件。Git 本身就是免费开源软件，官方渠道下载没有任何门槛。

2.3 安装前的两个决策：编辑器与终端

安装向导中间会问默认编辑器，这其实是一个提前决策项。如果你电脑上已经装了 VS Code，那直接选 Visual Studio Code；如果还没装，建议先把 VS Code 装好，再回头装 Git。因为 VS Code 自带集成终端、Git 面板和大量前端插件，和 Git 搭配起来是最顺手的。如果你不想装 VS Code，选 Notepad++ 或 Vim 也能用，但在 Windows 上默认编辑器的体验差距很明显，尤其是查看提交信息和合并冲突的时候。

终端方面，我强烈建议提前装 Windows Terminal。它能把 PowerShell、CMD、Git Bash 都整合到同一个窗口里，用标签页切换，而且对 UTF-8 中文的支持比老式控制台好很多。装了 Windows Terminal 之后，Git Bash 的中文乱码概率会大幅降低，至少能少跟编码问题纠缠半天。这个决策不影响安装过程，但会影响你后面用 Git 的日常体验。

3. 安装全流程：从双击到验证，每个选项都给你讲清楚

3.1 欢迎页、信息与安装路径

双击安装包后，第一页是 GNU GPL 许可说明，直接 Next。第二页会让你选安装路径，默认是C:\Program Files\Git。很多同学喜欢把软件装到 D 盘，但 Git 这个工具我建议放在默认路径，原因是安装向导会自动把 PATH 环境变量指向这个位置，后续排查问题、写脚本、配 CI 都是按默认路径假设的。

如果你确实想装到 D 盘，请务必保证目录是纯英文且没有空格，比如D:\Git。我之前见过有人装到D:\软件\Git这种路径，结果某些命令行工具解析路径时直接报错，非常折腾。接下来是选择开始菜单文件夹，保持默认即可。对于弹出的“Select Additional Tasks”页面，里面有些组件要重点看，我放在下一节说。

3.2 选择组件：哪些该勾，哪些可以放着

安装向导的“Select Components”页面是第一个值得停下来看的地方。默认选项已经比较合理，我实际安装时只在默认基础上做了一处微调。下面这个表格是我根据个人经验整理的勾选建议：

需要注意，前端项目如果只是常规业务代码，不涉及视频、设计稿、二进制资源，Git LFS 确实用不上；但你永远不知道下一个项目会不会需要，保留它不会影响日常操作，只是多装一个插件而已。“Associate .sh files to be run with Bash”我会取消，因为 Windows 上偶尔会有其他 IDE 或脚本工具需要处理 .sh 文件，默认关联到 Git Bash 后可能造成双击文件行为变得不可预期。

3.3 默认编辑器、PATH 环境与 SSH 客户端

“Select Default Editor”页面会让你选 Git 默认使用的文本编辑器。如果前面已经装了 VS Code，这里选Visual Studio Code最合适。选完之后，以后 Git 需要打开交互式编辑器（比如写提交信息、处理 rebase 的时候）都会自动调用 VS Code，体验比 Vim 友好得多。如果你没装 VS Code，最低限度选 Notepad++，不要选 Vim，因为新手在 Vim 里不知道怎么保存退出，会卡在提交信息编辑页。

接下来是“Adjusting your PATH environment”，这一页非常关键。三个选项分别是：仅从 Git Bash 使用 Git、从命令行和第三方软件使用 Git、从命令提示符使用 Git 并覆盖系统工具。我每次都选第二项：Git from the command line and also from 3rd-party software。这样 VS Code、JetBrains 系列、各种脚本都能直接调用git命令。不要选第三项，因为它会把 Git 自带的 Unix 工具混进系统 PATH，覆盖 Windows 自带的find、sort等命令，很容易引起连锁反应。

SSH 可执行文件那一页，默认选中Use bundled OpenSSH，我建议保持默认。Git for Windows 自带的 OpenSSH 和 Git 的配合经过了充分测试，你不用额外安装任何东西。只有当你的机器上已经有系统级 OpenSSH 服务并且需要统一管理密钥时，才考虑切到系统 SSH，普通前端项目没必要折腾。

3.4 HTTPS 传输后端与行尾转换

这一节有两页需要重点说明：HTTPS 传输后端和行尾转换。

HTTPS 传输后端有两个选择：Use the OpenSSL library和Use the native Windows Secure Channel library。默认是 OpenSSL，绝大多数场景都适用。如果你所在的公司网络环境有 HTTPS 流量拦截，或者 Git 仓库用的是 Windows 自签名证书体系，选后者的好处是 Git 会直接信任 Windows 系统的证书库，省去手动配 CA 的麻烦。但我个人更推荐默认 OpenSSL，因为它在 Git 生态里兼容性更好，遇到证书问题我们可以用后面提到的http.sslCAInfo来解决，而不是依赖系统底层行为。

行尾转换页面就是前端开发经常说的 CRLF/LF 问题。默认选项是Checkout Windows-style, commit Unix-style line endings，也就是检出到工作区时转成 Windows 的 CRLF，提交到仓库时统一转成 Linux 生态的 LF。这个默认选项对 Windows 上的前端开发基本是“能用且省心”的。但我必须补充一句：真正的解决方案不在安装向导里，而在仓库根目录的.gitattributes文件。后面我会专门讲，这里先记住一个原则：要么全队统一用默认选项，要么全队统一用.gitattributes强制换行符，千万不要一半人 default、一半人手动改。

3.5 终端模拟器、git pull 行为与凭据管理器

终端模拟器页面会让你选 MinTTY 还是 Windows 默认控制台。如果你平时用 Windows Terminal，选Windows' default console更合适，因为 MinTTY 在 Windows Terminal 里偶尔会出现光标渲染和复制粘贴的兼容性问题。如果你喜欢 Git Bash 独立弹窗、并且看重彩色输出效果，那 MinTTY 也不错。我自己的选择是 Windows Terminal + 默认控制台，整体稳定一些。

git pull的默认行为有三个选项：默认快进或合并、rebase、只允许快进。我建议保持默认的Default (fast-forward or merge)，因为对前端团队来说，git pull产生一个合并提交并不是灾难，反而更容易理解。如果你个人偏好在拉取时保持线性历史，可以选 Rebase，但要注意这会对所有仓库生效，团队项目中如果习惯不一致，反而会造成额外冲突。我更推荐的做法是：全局不动，在单个仓库里需要时手动git pull --rebase。

凭据管理器页面务必选择Git Credential Manager。这个组件会在你第一次使用 HTTPS 克隆或推送时，弹出一个登录窗口，帮你把账号密码或 Token 安全地保存到 Windows 凭据管理器里，之后就不用反复输入了。如果你在这里选了 None，那么以后每次 HTTPS 访问都要手动输密码，非常痛苦。尤其是现在 GitHub、GitLab 都推荐用 Personal Access Token 代替密码，配合凭据管理器会顺滑很多。

3.6 安装完成后的验证命令

安装完成后，在 Windows Terminal 或 CMD 里执行下面三条命令，确认安装正确：

git --version where git git config --list --show-origin

git --version会输出类似git version 2.53.0.windows.2的版本号，说明 Git 本体可用。where git会显示git.exe的绝对路径，通常是C:\Program Files\Git\cmd\git.exe，这一步确认 PATH 是否生效。如果提示找不到命令，先重新打开终端，还是不行就检查环境变量。git config --list --show-origin会列出当前所有配置以及每个配置来自哪个配置文件，这个命令在日后排查问题时特别有用，能一眼看出某个配置是不是被全局或系统级配置覆盖了。

到这里，Git 本体安装就完成了。但如果你现在直接开项目，大概率会遇到提交作者信息缺失、中文乱码、每次都要输密码这些问题。接下来是配置环节。

4. 安装后的基础配置：把 Git 调成前端开发顺手的样子

4.1 第一件事：配置 user.name 和 user.email

安装完成后的第一件事，不是 clone 项目，而是先告诉 Git 你是谁。如果不配置，第一次提交会直接报错，提示Please tell me who you are。执行：

git config --global user.name "你的名字" git config --global user.email "you@example.com"

这里注意，--global表示对当前 Windows 用户的所有仓库生效，写入位置在C:\Users\你的用户名\.gitconfig。如果你有多个 Git 账号，可以在单个仓库里用不带--global的配置覆盖全局值。我见过不少同学全局邮箱写了自己公司的邮箱，结果开源项目提交也带着公司域名，后面处理起来非常麻烦。建议全局项尽量用个人常用邮箱，公司项目再在仓库目录下单独覆盖。

关于邮箱隐私，如果你在用 GitHub，可以在 GitHub 设置里开启邮箱隐私保护，然后使用类似123456+username@users.noreply.github.com这种 noreply 邮箱。因为 GitHub 现在已经会拦截暴露真实邮箱的 push，不加配置的话很容易在提交时被拒。

4.2 默认分支名、提交规范与常用别名

Git 的默认初始分支名之前一直是master，现在主流的托管平台和工具都默认main。如果你用git init初始化仓库时发现分支名还是 master，可以全局设置：

git config --global init.defaultBranch main

前端项目的提交信息，建议直接采用 Conventional Commits 规范，也就是feat、fix、docs、style、refactor、perf、test、chore这些前缀。因为现在很多团队都上了 commitlint 和 lint-staged，提交信息不符合规范时直接 CI 报红。规范的提交信息长这样：

git commit -m "feat(login): 新增登录页表单校验" git commit -m "fix(user): 修复头像上传失败导致的页面崩溃"

我还会配置一些常用别名，能明显减少日常输入量：

git config --global alias.st status git config --global alias.co checkout git config --global alias.cm commit git config --global alias.br branch git config --global alias.lg "log --graph --pretty=format:'%h -%d %s (%cr) <%an>' --abbrev-commit"

配置完之后，输入git lg就能看到带图表的提交历史，比默认 log 直观太多。这条命令里的格式串如果你记不住，直接复制就行，实测在 Git Bash 里运行没问题。

4.3 SSH 密钥与免密登录配置

HTTPS 方式配合 Git Credential Manager 已经能记住密码，但我个人更推荐配置 SSH 免密登录。一次配置完成后，不管是git clone git@github.com:xxx/xxx.git还是 push，都不需要再输任何凭据。步骤很简单。

先在 Git Bash 里执行：

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

这里把you@example.com换成你自己的邮箱。执行后会问你要保存路径和密码短语，直接回车使用默认路径~/.ssh/id_ed25519，密码短语可以留空，也可以在安全需求高的时候设置。生成完成后，启动 ssh-agent 并将私钥加入：

eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519

然后查看公钥内容：

cat ~/.ssh/id_ed25519.pub

把输出的整串内容复制下来，粘贴到 GitHub 的Settings -> SSH and GPG keys -> New SSH key，或者公司 GitLab 的Preferences -> SSH Keys里。最后验证：

ssh -T git@github.com

如果看到类似Hi username! You've successfully authenticated的提示，就说明 SSH 配置成功了。现在很多公司 GitLab 用的也是同一套机制，只是验证地址换成git@gitlab.com或公司内网域名。注意不要把密钥文件本身提交到任何仓库里，公钥可以公开，私钥必须留在本地。

4.4 中文乱码与换行符：Windows 前端必调项

在 Windows 上装完 Git 后，最容易遇到的是中文文件名显示成八进制编码。默认情况下，git status会把中文文件名显示成"\346\226\207\344\273\266.txt"这种形式，看着非常头疼。处理方法是：

git config --global core.quotepath false

这个配置的意思是：不要对非 ASCII 文件名进行转义，让 Git 直接显示 UTF-8 中文。配置之后，git status、git diff里的中文文件名就能正常读了。如果你在 Git Bash 里看到提交信息是中文但显示乱码，可以在 Git Bash 窗口标题栏右键 → Options → Text → Character encoding 里选 UTF-8。如果你用 Windows Terminal，还需要确认 Git Bash 的 profile 没有覆盖编码设置。

换行符的问题我前面提过，安装向导的默认配置是core.autocrlf为 true。在 Windows 工作区里，文件会被换成 CRLF，提交到仓库时转成 LF。这个策略单独用没问题，但一旦仓库里混入了\r字符，diff 会满屏红。最理想的方案是在仓库根目录加一个.gitattributes文件，内容可以是这样：

* text=auto eol=lf *.png binary *.jpg binary *.gif binary *.ico binary

这几行的意思是：文本文件统一使用 LF，图片文件标记为二进制不做行尾转换。这样不管在 Windows、Linux 还是 macOS 上，Git 都会按同一套规则处理，团队协作就不会因为换行符打架。如果项目已经存在大量 CRLF 文件，可以在和团队确认后执行git add --renormalize .一次性规范化，但这会产生大规模 diff，最好在单独分支上做并让团队提前知晓。

5. 前端项目里的 Git 工作流与工具链联动

5.1 初始化仓库与 .gitignore 的标准姿势

新前端项目开始时，git init之后第一件事就是写.gitignore。很多新手喜欢等到提交时发现 node_modules 被加进来才想起来忽略，这时候已经晚了。标准的前端.gitignore至少要包含这些内容：

node_modules/ dist/ coverage/ .DS_Store *.log .env .env.local .env.*.local

node_modules永远是第一优先级，必须忽略；dist和coverage是构建产物，不该进仓库；.env.local这类文件里可能存本地密钥，绝不能提交。但这里要特别提醒：package-lock.json、pnpm-lock.yaml、yarn.lock千万不能忽略。它是依赖锁定和团队协作的关键，很多前端项目线上构建出问题，就是因为有人把 lockfile 删了或者忽略掉了，导致 CI 拉到的依赖版本不一致。

如果项目已经误提交了node_modules，光在.gitignore里加也没用，因为 Git 只会忽略未跟踪文件。需要先把它从索引里移除：

git rm -r --cached node_modules git commit -m "chore: remove node_modules from version control"

--cached参数很关键，它只删除 Git 索引里的记录，不会把磁盘上的node_modules文件夹真删掉。你本地依赖还能继续用，只是不再被提交。

5.2 分支模型与提交粒度怎么配合前端迭代

前端项目的分支模型主要有两种趋势。一种是比较经典的main+develop+feature/*+release/*，适合中大型项目，每次迭代有明确的环境归属。另一种是轻量化的main+feature/*，配合持续部署，适合小团队和快速迭代。不管用哪种，核心思想都是：main分支保持可发布状态，功能开发都在独立分支上进行，合并前经过 Code Review。

提交粒度对前端项目的可维护性影响很大。我见过最头疼的提交是fix: 修复一堆问题，里面混了三个 bug 的改动和一个样式调整，等要回滚的时候完全没法精准处理。比较好的做法是一个功能一个提交，小步提交、频繁提交，每个提交都能独立通过构建。比如一个登录页功能，可以拆成“新增登录接口请求方法”“新增表单校验”“接入页面 UI”“补充单元测试”四个提交。这样做 MR/PR 的时候，评审人也能按提交一个一个看，体验完全不同。

5.3 VS Code 的 Git 面板与命令行的配合

VS Code 安装好后会自动识别系统 Git，左侧源代码管理面板会显示当前分支、改动文件、暂存区状态。对前端开发来说，VS Code 的 Git 面板适合做这两件事：一是快速查看改动，点开文件就能看到每个 diff 的增删行；二是做文件级别的暂存和提交，右键文件就能git add，输入提交信息后直接提交。

但在处理 rebase、复杂冲突合并、或者需要精细控制暂存区时，我仍然会切回命令行。原因很简单：命令行能精确表达你的操作意图，而且报错信息更完整。比如你只需要暂存某个文件里的一部分改动，VS Code 做不了，命令行可以用git add -p交互式拆分。我的个人习惯是：用 VS Code 看改动和解决冲突，用命令行执行 commit、rebase、cherry-pick、stash 这类需要精确控制的操作。

这里还有一个 Windows 特有的坑：文件重命名只改大小写时，Git 默认可能检测不到。因为core.ignorecase在 Windows 上默认是 true。比如把README.md改成readme.md，在 Windows 文件系统里可能就是同一个文件，Git 会认为没有变化。正确操作是用git mv README.md readme.md，如果改动已经发生但 Git 没跟踪，可以先调整core.ignorecase false，再让 Git 重新扫描一次。

5.4 和其他工具的联动：SourceTree、WebStorm 与团队协作提醒

如果你的团队用 SourceTree，安装完系统 Git 后，最好在 SourceTree 的设置里把 Git 版本指到系统 Git，而不是用 SourceTree 内置的旧版本。因为内置 Git 可能版本落后，和 CI 用的版本行为不一致。JetBrains 系列工具比如 WebStorm、IDEA 会自动识别系统 Git，一般不需要额外配置，但建议在设置里确认一下。

团队协作方面，我吃过不少亏，总结下来有三条经验。第一，换行符策略必须全队统一，要么都用默认的core.autocrlf=true，要么都用.gitattributes强制 LF，不能有人改、有人不改。第二，提交规范最好用工具强制，commitlint 加 lint-staged 在 pre-commit 阶段就能拦截不规范的信息和不符合 ESLint 规则的代码，别靠自觉。第三，Git 版本尽量统一到相同或相近版本。2.53 这种新版本和 2.30 这种老版本在冲突算法、安全策略上都有差异，版本相差太远时，即使配置相同，行为也可能不一致。

6. 常见问题与排查实录

6.1 安装后终端提示“git 不是内部或外部命令”

这个问题绝大多数原因是 PATH 没有配置好。安装时如果选了Use Git from Git Bash only，那么 CMD、PowerShell 和 VS Code 终端里都找不到git命令。解决办法有两种：第一，重新运行安装程序，在“Adjusting your PATH environment”页面改成第二项；第二，手动去系统环境变量里的Path添加C:\Program Files\Git\cmd，然后重新打开终端。

如果你是刚安装完就执行git --version报错，先别急着改环境变量，把当前终端窗口关掉再重新打开。Windows 的环境变量在终端启动时读取一次，不重启终端不会生效。这个原因看着简单，但真的能卡住不少人。

6.2 Git Bash 里中文文件名和提交信息乱码

中文乱码可以分两类。文件名乱码基本就是core.quotepath没配置，执行git config --global core.quotepath false就能解决。提交信息乱码要分终端还是文件存储。如果文件内容在 VS Code 里显示正常，但 Git Bash 里git log显示乱码，那大概率是终端编码问题。在 Git Bash 窗口右键 → Options → Text → Character encoding 里选 UTF-8，或者用 Windows Terminal 时确认 profile 的编码设置为 UTF-8。

还有一类情况是git commit时用中文注释，但打开看是乱码，这可能是老的编辑器把文件存成了 GBK。现在 VS Code 默认 UTF-8，基本不会遇到这种问题，但如果你的core.editor指向了 Notepad，最好确认编辑器保存格式。实在不行，可以在全局设置里加上：

git config --global i18n.commitEncoding utf-8 git config --global i18n.logOutputEncoding utf-8

6.3 “detected dubious ownership”安全报错

Git 2.35 之后增加了一个安全机制：如果仓库目录的所有者与当前 Windows 用户不一致，Git 会拒绝执行命令，提示detected dubious ownership in repository。这个报错常见于以下场景：从压缩包解压出来的项目、U 盘复制过来的项目、或者使用管理员账号创建的文件夹被普通用户打开。

解决方法很简单，把对应目录加入 Git 的安全目录白名单：

git config --global --add safe.directory D:/code/my-project

如果你某个盘符下所有项目都报这个错，也可以直接把整个父目录加进去。网上有人建议用git config --global --add safe.directory '*'一劳永逸，我不推荐，因为这会关闭 Git 对所有目录的所有权检查，安全性大打折扣。比较合理的做法是只把你常用的开发目录加入白名单。

6.4 SSL certificate problem 自签名证书坑

公司内网 GitLab 如果用了自签名证书，执行git clone时报SSL certificate problem: self-signed certificate，很多人第一反应是关掉验证：

git config --global http.sslVerify false

这个操作确实能解决报错，但等于让 Git 不做任何证书校验，所有 HTTPS 请求都在裸奔。即使只是内网环境，我也不建议这么干。正确的处理方式是把公司证书导出成.crt文件，然后让 Git 使用这个 CA 文件：

git config --global http.sslCAInfo "C:/certs/company-ca.crt"

如果 Git for Windows 安装时你选了native Windows Secure Channel library，那么只需要把证书导入系统“受信任的根证书颁发机构”里，Git 会自动信任。总的来说，尽量用信任证书的方式解决，而不是一刀切关闭验证。

6.5 行尾符导致 diff 满屏红、ESLint 报错

现象是：只改了一行代码，git diff却显示整个文件被删除然后又新增。原因几乎可以断定是换行符从 CRLF 变成了 LF，或者反过来。排查方法：

git config --get core.autocrlf

如果输出 true，Git 会在提交时自动转换换行符。但仓库里某些文件可能已经被提交成 CRLF，这时候改动会触发整文件差异。另一个排查方法是直接在 VS Code 右下角看文件的行尾标识，能直观看到当前文件是 CRLF 还是 LF。

解决办法是统一.gitattributes，我前面已经写了示例。如果项目里已经有大量历史文件行尾不统一，建议先和团队确认，然后在分支上执行：

git add --renormalize . git commit -m "chore: normalize line endings"

ESLint 侧也可以配置linebreak-style: ["error", "unix"]，让 CI 在构建阶段就报出非 LF 文件，把问题控制在开发阶段。

6.6 提交身份错误与邮箱隐私保护

提交历史里显示的作者名字/邮箱不对，通常有两种原因。第一种是安装 Git 之后从没配置过user.name和user.email，Git 自动从 Windows 用户名leihua这种值生成了一个提交身份，看起来就非常奇怪。第二种是多账号使用混乱，比如公司仓库用了个人邮箱，或者反过来。

修正最近一次提交：

git commit --amend --reset-author

执行后会用当前仓库的user.name和user.email重写最近一次提交的作者信息。如果你改的是全局配置，需要先重新设置再执行上面的命令。历史提交的修改会更麻烦，要用git filter-branch或git filter-repo，但操作前务必和团队确认，因为会重写整个分支历史，可能导致其他人本地分支冲突。我建议普通情况下不要碰历史提交，重点是把当前和以后的提交身份弄对。

6.7 旧版本升级注意点

Git for Windows 升级通常直接覆盖安装，旧配置不会丢，因为配置都存放在C:\Users\你的用户名\.gitconfig和~/.ssh下，安装包不会动它们。但升级前我习惯先备份一下.gitconfig，万一手滑误删或者发现某个配置被新版本安全策略拒绝，还能快速恢复。

版本升级后有两个比较容易踩的点。一个是之前提到的safe.directory白名单，如果你之前用通配符*配置过，升级后可能被 Git 拒绝或要求重新确认。另一个是 SSH 密钥算法，老版本可能还支持一些旧算法，新版本为了安全默认关闭了，如果你一直用旧密钥连不上仓库，生成一个新的 Ed25519 密钥通常就能解决。

最后分享一个小技巧：装完 Git 后，别急着开项目，先花十分钟把.gitconfig、SSH 和.gitattributes模板都准备好。我在多个团队里发现，绝大多数 Git 混乱都来自“装完就用，从不配置”。照着前面几步做一遍，后面能省下大量时间。