企业官网建设流程全解析

上周帮同事排查一个问题，他 clone 完项目在 IDEA 里点提交，控制台弹出一行红字：git : 无法将“git”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。折腾了半小时才发现，他装的是 TortoiseGit，以为“小乌龟”里自带 Git 内核——这大概是Git 安装环节最经典的一个误会。类似的还有：装完 Git 结果在 CMD 里敲git没反应、SSH 密钥配了但一直提示认证失败、克隆下来的目录里空空如也只剩一个隐藏文件夹。

这篇内容就是把这些事一次性讲透。它覆盖从下载安装包、逐页读懂安装向导、验证环境变量、完成全局配置、打通 SSH 免密、到接入 IDEA / VSCode / 小乌龟的完整链路，最后再还原几个高频报错的排查过程。适合三类人：完全没接触过版本控制的新手、装过一次但没搞明白每个选项含义的人、以及环境总是出问题的“重装党”。不管你是 Windows 还是需要给团队写一份标准安装文档，下面的步骤都可以直接照着做。

1. 搞清楚 Git 到底装了什么，再动手

1.1 一次安装背后其实塞了四样东西

很多人以为装 Git 就是装一个命令行工具，其实 Git for Windows 这个安装包一次性给你塞了四样东西，理解这一点后面很多报错就顺了。

第一是Git 核心程序，也就是git.exe本体，所有版本控制操作的执行者。第二是Git Bash，一个基于 MinTTY 的模拟终端环境，它让 Windows 上也能用ls、cat、grep这些类 Unix 命令，脚本兼容性最好。第三是Git GUI，一个官方自带的极简图形界面，用的不多但关键时刻能救急，比如看差异、做暂存。第四是TortoiseGit——注意，它不在 Git 官方安装包里，是另一个独立的第三方程序，中文俗称“小乌龟”，它只是一个图形壳，必须依赖本机已装好的 Git 才能工作。

我见过太多人只装了 TortoiseGit，然后在命令行敲git报“不是内部或外部命令”，转头去论坛发帖问“小乌龟为什么用不了”。答案是：它从来没打算替代 Git 本体。

1.2 为什么“安装”这一步能卡住这么多人

一个命令行工具而已，理论上解压即用，为什么会有这么多坑？原因在于 Windows 和 Unix 的底层差异。Git 诞生于 Linux 世界，它默认文件路径区分大小写、默认换行符是LF、默认终端是/bin/bash；而 Windows 用的是反斜杠路径、CRLF换行、CMD/PowerShell 终端。安装向导里那一堆选项，本质上都是在问同一件事：这些差异你要怎么处理？

选错了会怎样？举个最典型的：core.autocrlf配置不当，会导致每次git status都显示整个文件被修改，实际内容一个字没动，全是换行符在“作妖”。再比如 PATH 选项选错了，Git 只在 Git Bash 里能用，IDE 里一调就报找不到可执行文件。

所以别急着点“下一步”。下面我把安装向导的每一页都拆开讲。

2. 下载渠道、版本号与文件校验

2.1 官方渠道与镜像站怎么选

Git 的 Windows 版本由 Git for Windows 项目单独维护，官网的下载入口在gitforwindows.org，它会把你导向托管的发布页。如果下载速度不理想，可以考虑国内部分高校和云厂商提供的开源镜像站，它们会同步发布资产，例如清华大学开源软件镜像站、华为云镜像、腾讯云镜像等，一般在“github-release”这类目录下按项目名检索即可。

提示：无论从哪里下载，都建议核对安装包的哈希值。官网发布页通常会给出 SHA-256 校验串，下载完成后用certutil -hashfile 文件名 SHA256比对一次，几十秒的事，能避免拿到被篡改或被捆绑过的安装包。

我个人的习惯是：优先官方，官方慢就换镜像，但校验步骤一次不省。安装包体积大概五六十兆，多等两分钟比事后排查中毒要划算得多。

2.2 版本号怎么读，要不要追新

Git 的版本号形如2.45.2，第一位大版本极少变动，第二位小版本带来新功能，第三位是修复补丁。对你的日常使用来说，同一个大版本内，装最新的稳定版就行，不用纠结。

真正需要注意的是两件事：

还有一个容易被忽略的点：如果你所在项目用了 Git LFS 管理大文件，安装时务必勾选 LFS 组件（安装向导里有独立勾选项），否则克隆下来的大文件会变成一堆指针文本。

3. 安装向导逐页拆解，每个勾选框的实际影响

这一节是全文分量最重的部分。我把典型 Windows 安装向导的十几个页面按顺序过一遍，重点讲清楚每个选项“选了会怎样、不选会怎样”。

3.1 组件选择页：哪几个勾是必须的

这一页勾选项最多，也最容易点错。我的推荐配置如下。

必勾的：Windows Explorer integration下的Git Bash Here和Git GUI Here。这两个会在文件夹右键菜单里加菜单项，是日常用得最频繁的入口，尤其是“在某个目录右键直接开 Git Bash”，省掉无数次cd。Git LFS看项目需求，用大文件的话勾上。Associate .git* configuration files也建议勾，双击.gitconfig就能进编辑器。

可以放心不勾的：Additional icons里的桌面图标，命令行工具放桌面纯属占地方。Check daily for Git for Windows updates国内网络环境下经常连不上更新服务器，勾了只会每天弹一次失败提示，不如手动升级来得干脆。Scalar和Add a Git Bash Profile to Windows Terminal属于高级特性，前者是给超大仓库做性能优化的，后者方便你把 Git Bash 挂进 Windows Terminal，按需选。

有一个勾选项要特别当心：Associate .sh files to be run with Bash。勾上之后，任何.sh脚本双击就直接执行，不再弹编辑器。如果你偶尔要编辑脚本文件，这会让你很抓狂——双击就跑了，想改内容都进不去。

3.2 默认编辑器的选择，以及那个“退不出去”的坑

向导会让你选默认编辑器，候选包括 Nano、Vim、Notepad++、VS Code 等。这个选项影响的是git commit不带-m参数时弹出的那个编辑窗口，以及合并冲突时的提交信息编辑。

新手请务必避开 Vim。我在社群里见过太多次求助：“Git 卡住了，光标一直在闪，键盘敲什么都没反应。”那不是卡住，那是你进了 Vim 但没有进入插入模式。退出方式是先按Esc，再输入:wq回车。

Nano 相对友好，底部会直接显示快捷键提示，退出是Ctrl+X。但如果你本来就装着 VS Code，直接选它是最舒服的——弹出图形窗口，改完保存关闭即可，没有学习成本。

3.3 PATH 环境变量三档：这是全流程最关键的一页

安装向导里有一个页面会给你三个单选，问git命令放在哪里可用。这一页选错，就是“命令找不到”报错的根源。

• Use Git from Git Bash only：不修改 PATH。意味着只有打开 Git Bash 才能用git命令，CMD、PowerShell、IDEA、VSCode 全都调不到。除非你有极特殊的隔离需求，否则不要选。
• Git from the command line and also from 3rd-party software：官方推荐项。加到 PATH，但不覆盖 Windows 自带的工具。选这个。
• Use Git and optional Unix tools from the Command Prompt：把 Git 附带的一批 Unix 工具也塞进 PATH，包括find、sort、ls等。危险在于，这些工具会覆盖 Windows 同名命令。比如find在 Windows 下是查找文本的命令，被覆盖成 Unix 版本后，一些老脚本和老工具链会直接报错。除非你非常清楚自己在干什么，否则别碰。

注意：这一页如果误选了第一项，不用重装。手动把Git安装目录\cmd加到系统环境变量 Path 里，效果一样，具体操作在第 4 节讲。

3.4 SSH 后端、HTTPS 后端与换行符转换

再往后几页，是三个有“标准答案”的选项。

SSH 可执行程序：选Use bundled OpenSSH，使用 Git 自带的 SSH 客户端。这样密钥路径、配置文件都在 Git 的掌控范围内，行为可预期。选外部 OpenSSH 的话，如果你系统里同时装了多种 SSH 工具，容易出现“密钥在 A 目录、找的是 B 目录”的迷惑情况。

HTTPS 传输后端：选Use the native Windows Secure Channel library。它走 Windows 系统自带的证书库，企业内网证书、系统代理设置都能自动继承，用起来省心。如果遇到证书链异常，也可以换回 OpenSSL 库，两者可以后期用git config --global http.sslBackend切换。

换行符转换：选第一项Checkout Windows-style, commit Unix-style line endings。含义是：检出到工作区时把LF转成CRLF，提交入库时再转回LF。这样 Windows 上的编辑器（尤其是记事本时代的老工具）看着舒服，仓库里存的又是跨平台通用的格式。对应配置就是core.autocrlf=true。

3.5 终端模拟器、pull 行为与凭据助手

终端模拟器：选Use MinTTY。它支持窗口自由缩放、字体自定义、复制粘贴快捷键更顺手。唯一的小遗憾是它不是原生 Windows 控制台，某些交互式程序（比如需要输入密码的老式提示）可能显示异常，通过winpty前缀可以绕过，这是后话。

git pull默认行为：保持Default (fast-forward or merge)即可。这一项影响的是本地有提交、远端也有新提交时，git pull会怎么处理。新手阶段不要选 rebase，线性的历史确实好看，但冲突处理逻辑更绕，容易把自己搞懵。

凭据助手：选Git Credential Manager。这是解决“免密”和“总提示登录”问题的关键组件，它会把你的凭据安全地存进 Windows 凭据管理器，之后对同一个远程仓库的推送拉取就不用反复输密码了。

其他选项：Enable file system caching勾上，能明显加快git status在大仓库里的响应速度。Enable symbolic links需要系统开启开发者模式才真正生效，普通用户勾不勾都行。

4. 装完之后的验证与 PATH 排查链路

4.1 三条命令确认安装真的成功

安装向导跑完，先别急着关窗口。打开一个全新的终端（这点很重要，老的 CMD 窗口读的是旧环境变量），依次执行：

git --version git --exec-path where git

第一条输出类似git version 2.45.2.windows.1，说明命令解析成功。第二条打印 Git 内部命令所在的目录，用来确认它调用的是你刚装的这一份，而不是系统里残留的旧版本。第三条在 Windows 下会列出所有匹配git的路径——如果输出了多条，说明你机器上有多个 Git，后面大概率会遇到版本混乱，需要清理。

顺手再确认一下配置文件的落地位置：

git config --global --list --show-origin

--show-origin会把每条配置来自哪个文件一并标出来，排查“配置到底生效了没”时特别好用。

4.2 “无法将 git 项识别为 cmdlet”的完整排查

这个报错我处理过不下二十次，排查顺序基本固定。

第一步，确认到底装没装。去安装目录看一眼，默认在C:\Program Files\Git\cmd\git.exe。如果这个路径不存在，那没什么好排查的，回去重装。

第二步，看cmd目录有没有进 PATH。打开“系统属性 → 高级 → 环境变量”，在系统变量的Path里找有没有C:\Program Files\Git\cmd。注意是要加cmd子目录，不是 Git 根目录，也不是bin目录（bin里是给 Bash 环境用的）。

第三步，确认改完之后重开终端。环境变量在进程启动时读取，已经开着的窗口不会感知变化。这一条看似废话，但它是“我明明配好了还是不行”的头号原因。

第四步，检查是否有多个终端会话被冻结。VSCode 的集成终端、IDEA 的 Terminal 都要整个重启，光关标签页不够。

第五步，如果 PATH 正确、终端也重启了还是不行，那就是命令被更高优先级的路径劫持了。用where git看输出顺序，把靠前的那条非法路径挪走或删掉。

还有一个 PowerShell 独有情况：PowerShell 里如果定义了名为git的函数或别名，会覆盖外部命令。执行Get-Command git就能看到它到底解析成了什么，是这个原因的话用Remove-Item Alias:git清掉。

5. 全局配置：身份、换行、别名与免密

5.1 user.name 和 user.email 到底影响什么

刚装完的 Git 是“匿名”的，第一次提交就会拦你：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

这两条不是登录账号，Git 本身没有账号体系。它们只是被打包进每一条提交记录里的元信息，用来标记“这次提交是谁做的”。但正因为如此，它们必须和你代码托管平台上注册的邮箱保持一致，否则平台无法把提交归属到你的账号上，你的贡献图会是一片空白。

提示：如果公司项目和个人项目要区分身份，可以在具体仓库里用不带--global的命令再设一次，仓库级配置优先级高于全局配置。

5.2 core.autocrlf 的正确取值与验证

安装时选了 Windows 风格换行，配置项应该是core.autocrlf=true。用下面这条确认：

git config --global core.autocrlf

如果团队统一要求仓库内保留CRLF，那就设成false；如果你在 macOS / Linux 上工作，通常设成input（提交时转LF，检出时不动）。

判断有没有踩这个坑，有个很直观的信号：git status显示某个文件被修改了，但你打开一看内容没变，用git diff也只看到整行整行的红绿。这时候用git diff --stat看改动行数，如果是“整个文件全改”，八成就是换行符。修复办法是统一配置后，把工作区文件重新检出一次：git rm --cached -r .再git reset --hard。

5.3 凭据缓存与别名提速

免密登录有两个方向。走 HTTPS 的话依赖凭据助手：

git config --global credential.helper manager git config --global credential.helper store

前者是 Windows 凭据管理器，安全性更好；后者是把账号密码明文写进用户目录的.git-credentials文件，方便但明文存储，不建议在共用电脑上使用。我通常推荐前者，SSH 方案则见下一节。

别名是提升效率的隐藏加分项。Git 允许你给常用命令起短名：

git config --global alias.st "status -sb" git config --global alias.lg "log --oneline --graph --all --decorate" git config --global alias.last "log -1 HEAD"

之后git st就等于git status -sb，git lg直接出一张带分支图的历史。这几条是我每次装完 Git 必配的，长期用下来能省下大量敲键盘的时间。

6. 打通远程仓库：SSH 密钥从生成到验证

6.1 生成密钥对与文件落位

SSH 方案比 HTTPS 更适合长期使用，配好之后推送拉取全程无感。第一步生成密钥对：

ssh-keygen -t ed25519 -C "你的邮箱"

ed25519是目前推荐的算法，密钥短、安全性高。老系统如果不支持，可以退回到rsa并指定 4096 位：ssh-keygen -t rsa -b 4096 -C "你的邮箱"。

连按三次回车，默认会把密钥写到C:\Users\你的用户名\.ssh\下，生成id_ed25519（私钥）和id_ed25519.pub（公钥）。私钥绝对不能外发，哪怕对方说是平台客服。公钥才是你要贴出去的那一半，用cat ~/.ssh/id_ed25519.pub打印出来，或者用编辑器打开.pub后缀的文件复制全文。

6.2 把公钥挂到托管平台上

登录你的代码托管平台，进入个人设置里的 SSH 公钥管理页面，新建一条，把刚才复制的完整内容粘进去。注意复制时要包含开头ssh-ed25519和结尾的邮箱备注，中间不能断行、不能多空格——这是最常见的失败原因，很多人复制时漏掉尾部几个字符。

标题随便填一个能认出来的，比如“公司台式机”。一台机器一个公钥条目，将来要吊销某台设备就精准得多。

6.3 首次连接的验证与常见拒绝

配置完成后验证：

ssh -T git@gitee.com ssh -T git@github.com

第一次连接会问你Are you sure you want to continue connecting?，输入yes回车即可，这会把对方主机的指纹存进known_hosts。之后看到类似Hi xxx! You've successfully authenticated就说明通了。

如果看到Permission denied (publickey)，按这个顺序查：公钥有没有真的粘进平台；私钥文件名是不是非默认名（非默认的话需要在~/.ssh/config里用IdentityFile指定）；当前用户目录下的.ssh文件夹权限是否异常；是不是有多个密钥导致 SSH 挑错了。

还有一种情况是git clone时报Host key verification failed，通常是known_hosts里存了旧的、已更换的主机指纹。删掉对应那一行再连一次即可。

7. 把 Git 接进日常工具链

7.1 IDEA 里的 Git 路径设置陷阱

IDEA 一般能自动探测到 Git。路径在File → Settings → Version Control → Git，点一下Test看版本号能不能出来。出不来就手动指定到C:\Program Files\Git\cmd\git.exe。注意是cmd目录下的那个，不是根目录下的git.exe，也不是bin目录下的，这两处选了之后 IDEA 经常识别不出。

提交代码的常规流程是：Ctrl+K打开提交窗口，勾选要提交的文件，写提交信息，点 Commit；再Ctrl+Shift+K推送。如果推送时报认证失败，检查是不是 HTTPS 和 SSH 混用了——IDEA 里每个远程地址是独立的，URL 写成https://就永远走凭据助手，写成git@才走 SSH。

7.2 VSCode 的分支、暂存与冲突

VSCode 内置了 Git 支持，左侧源代码管理面板能直接看到改动。它的一个特点是“按块暂存”：鼠标悬停在改动行上会出现小按钮，可以把某个代码块单独暂存，做原子提交时特别有用。

VSCode 里做git pull遇到冲突，编辑器会给冲突文件标出Accept Current/Accept Incoming/Accept Both三个按钮，点完记得手动检查一遍结果再提交。千万不要三个按钮盲点，尤其是两个分支都改了同一段逻辑的时候，机器的自动合并结果经常是语法正确、逻辑错误。

7.3 小乌龟 TortoiseGit 的安装顺序与语言包

再强调一次顺序：先装 Git for Windows，再装 TortoiseGit。装 TortoiseGit 的过程中它会问你 Git 的安装路径，如果本机没装 Git，这一步直接卡死。

装完之后，右键菜单里会出现 TortoiseGit 的选项。它有个很实用的场景：查看某个文件的逐行修改历史，右键 →TortoiseGit→Blame，比命令行直观得多。中文界面需要额外下载语言包并安装，然后在设置里的General → Language切换。

提示：如果右键菜单里只有 TortoiseGit 没有 Git Bash，说明安装 Git 时漏勾了Windows Explorer integration。不用重装，重新运行一遍安装包选Modify补上即可。

8. 几个高频报错的现场还原

8.1 fatal: not a git repository

完整报错是fatal: not a git repository (or any of the parent directories): .git。字面意思是：在当前目录及其所有上级目录里，都没有找到.git文件夹。

根因只有两类。一是你真的不在仓库里，比如打开终端默认落在C:\Users\你的用户名，然后直接敲git status。二是你在仓库里，但目录层级不对——比如项目根目录是D:\work\demo，你却在D:\work下执行命令。

排查方法很直接：git rev-parse --show-toplevel会打印当前仓库的根目录，报错就说明确实不在仓库内。用ls -a或dir /a看看有没有隐藏的.git文件夹。如果是从压缩包里解出来的项目，很可能压缩时把.git一起打包进去了又被解压工具忽略掉，这时候需要重新git clone一份。

8.2 login failed 与认证失效

这类报错通常长这样：login failed. check api token or gitlab version，或者推送时反复弹窗要密码。原因一般有三种：凭据助手里存的旧密码已经过期（比如平台强制改过密码，或者从密码认证切换成了令牌认证）；账号启用了双因素验证，普通密码不再可用；或者你换了账号，但凭据管理器还在用旧身份。

修复路径：打开 Windows 的“凭据管理器”，在“Windows 凭据”里找到对应的代码托管平台条目，删掉，下次推送时会重新弹窗让你输入。如果平台已经不支持密码认证，需要去平台生成一个访问令牌（Personal Access Token），用它当作密码使用。SSH 方案不存在这个问题，这也是我长期推荐 SSH 的原因之一。

8.3 提交信息写错与 commit --amend

提交信息打错字是常事，不用慌。

如果只是最近一次提交的信息错了，而且还没推送到远端：

git commit --amend -m "修正后的提交信息"

这条命令会用一个新的提交替换掉当前 HEAD，历史看起来像什么都没发生过。如果只是想补充漏掉的文件，先git add那个文件，再执行git commit --amend --no-edit，保留原信息只把文件补进去。

注意红线：如果这次提交已经推送到共享分支，不要用--amend。它会改写历史，导致别人的本地分支和远端对不上，下次拉取时一片混乱。已经推送的情况，老老实实再提交一条修正说明，或者用git revert生成一条反向提交。

8.4 克隆下来的目录是空的

git clone跑完，进目录一看只有.git一个隐藏文件夹，其他什么都没有。第一种可能：这个仓库确实只提交了空目录结构，或者你克隆的分支本身就是空的。用git branch -a看看远端有多少分支，git log --all --oneline看有没有提交记录。

第二种可能：克隆过程中断了但你误以为成功了。留意命令输出里有没有early EOF或index-pack failed之类的字样。网络不稳定导致的中断很常见，重试一次，或者加上--depth 1只拉最近一次提交，体积能小很多。

第三种可能：你克隆的是一个子模块引用，主仓库里那些目录其实是 submodule，需要额外执行git submodule update --init --recursive才能把内容拉下来。

最后分享一个我自己的习惯：每台新机器装完 Git，我会先建一个叫sandbox的空仓库，把git init、git add、git commit、git remote add、git push这条链路完整跑一遍，确认无误再动真实项目。花五分钟做一次全链路验证，比在正式项目里撞报错省心得多。另外，安装包和 SSH 密钥建议单独备份一份到加密移动盘，换机器时能省掉大半折腾。