1. Windows下安装Git看似简单选项背后的坑不少1.1 下载安装包与版本选择先说下载。Git官网是git-scm.com直接进download页面Windows版本会自动识别你的系统位数一般64位系统就下载64-bit版本。官网下载速度在某些网络环境下确实拉胯我建议直接在镜像源下载——阿里云镜像、清华镜像都有Git的Windows安装包版本可能比官网滞后几天但不影响使用。记住一点下载安装包之后先核对文件名和版本号Git的版本迭代不算快稳定版直接用就行没必要追最新。安装包里有一个容易被忽略的点安装路径。默认装在C:\Program Files\Git如果是公司电脑有权限限制建议改成用户目录下比如C:\Users\你的用户名\git。因为后续很多开发工具VS Code、JetBrains系列会自动探测Git的安装位置装在非默认路径时要记得在IDE里手动指定。1.2 安装向导中五个关键选项怎么选Git的安装向导看起来全程Next就行实际上有几个选项会影响后面的使用体验我一个个说。第一个是Select Components选择组件。默认选项里包含了Git Bash Here和Git GUI Here这两个一定要保留。作用是在Windows资源管理器的右键菜单里直接打开Git Bash终端非常实用。还有一个Associate .git configuration files和Associate .sh files建议勾上但Add a Git Bash Profile to Windows Terminal要看你的Windows版本Win11自带Windows Terminal的话可以勾Win10建议不勾避免profile冲突。第二个是Default editor默认编辑器。这里默认选的是Vim我强烈建议换成别的。Vim的退出方式对新手极不友好经常有人卡在commit信息编辑界面不知道怎么退出。如果你装了VS Code或Notepad就选对应的选项什么都不想装就选Nano——至少右上角有关闭按钮操作直观得多。第三个是Adjusting your PATH environment变量。三个选项里第二个Git from the command line and also from 3rd-party software是最佳选择。这个选项会把Git的可执行文件加进系统PATH这样CMD、PowerShell、以及各种IDE内嵌终端里都能直接用git命令。第三个选项仅Git Bash内使用不建议选否则用VS Code的终端敲git会提示git不是内部或外部命令。第四个是HTTPS backendHTTPS后端默认用OpenSSL保持默认。这个决定git clone走HTTPS协议时的SSL证书验证机制OpenSSL兼容性最好不要改。第五个是Line ending conversions行尾转换。默认是Checkout Windows-style, commit Unix-style line endings这个选项对绝大多数Windows用户是最优解后文我会专门讲这个坑。1.3 安装完成的验证方式装完以后打开Git Bash输入git --version能输出版本号就说明装好了。顺便看一眼git config --list如果提示没有配置文件是正常的还没到配置步骤。还有一个小事安装完成后先重启一下终端或IDE。Git安装过程中写入的PATH环境变量在已打开的终端里不会立即生效不重启的话执行git命令大概率还是报command not found。这个我见太多人踩过了。2. Git装好之后的第一件事基础配置2.1 user.name与user.email提交记录的身份证很多人git clone完就开始改代码等到第一次commit时才被Git教育。其实clone之前、或者第一次commit之前必须先把身份信息设置好。这两条命令的执行时机应该是安装后立刻做git config --global user.name 你的名字 git config --global user.email 你的邮箱--global表示全局生效写一次所有仓库共用。这个配置会写到C:\Users\你的用户名\.gitconfig文件里。为什么必须在clone之前先配置因为clone操作本身不校验身份但从clone下来的仓库里做git commit时Git必须用user.name和user.email生成提交信息缺了就会弹出一大段红色的Please tell me who you are错误提示。还有一点GitHub识别提交者身份靠的是这个邮箱。如果你的邮箱和GitHub账号绑定邮箱不一致提交虽然能成功但GitHub后台不会把它关联到你的账号头像上会显示成一个灰色默认头像的未知用户。这也是很多人提交了代码但绿格子不增加的原因之一。2.2 行尾符处理Windows开发者的第一道坎Windows和Linux/macOS的换行符不一样Windows用CRLF回车换行Unix系用LF纯换行。Git在跨平台协作时如果处理不当你会看到整个文件的每一行都被标记为变更这就是行尾符差异导致的全文件diff现象。默认配置下Git在Windows会做单向转换从仓库拉代码时把LF转成CRLF方便Windows的记事本和旧编辑器查看提交时再转回LF保证仓库里存的是Unix风格换行。这个默认方案对纯Windows团队是没问题的。但如果你参与的项目里有.sh脚本、Dockerfile、或任何需要在Linux环境运行的配置文件就要小心了。CRLF混入shell脚本会导致/bin/sh^M: bad interpreter这种诡异报错。我遇到过同事提交的docker-compose.yml里有CRLF整个容器起不来排查了半天。遇到这种跨平台项目建议把core.autocrlf设为false或inputgit config --global core.autocrlf false这样Git就不会做任何转换仓库里存什么就留什么。代价是Windows下用记事本打开可能显示成一行但用VS Code或Notepad看毫无问题。我的建议是如果你是纯个人使用且主要看代码关掉转换最省心。2.3 初始化默认分支名与后续配置Git 2.28之后的版本支持配置初始化仓库时的默认分支名。GitHub上的新仓库主分支叫main但本地git init默认还是master每次都会出现一条hint: Using master as the name for the initial branch的警告。眼不见心不烦直接统一git config --global init.defaultBranch main还有一个我建议装完就配的pull默认行为。Git 2.27之后git pull有可能因为分支分叉而报错提前设置合并策略能少点麻烦git config --global pull.rebase false这样git pull走merge模式不会产生rebase导致的提交历史重写问题对新手最友好。3. 用git clone拉下GitHub项目完整实操3.1 获取仓库地址的正确方式打开任意一个GitHub仓库页面能看到绿色醒目的Code按钮点开后有三种获取方式HTTPS、SSH、Download ZIP。新手用HTTPS最省事URL格式是https://github.com/用户名/仓库名.git不需要提前配置任何密钥复制后直接clone即可。SSH方式需要你先在本地生成密钥对、把公钥添加到GitHub账号里格式是gitgithub.com:用户名/仓库名.git好处是一次配置后续clone和push都不需要输密码。Download ZIP虽然也是下载但它只是快照没有.git目录拉下来之后无法git pull跟踪更新严格来说不算clone。有一点值得注意如果你自己项目的仓库是私有Private状态HTTPS方式clone时会要求输入用户名和密码密码那栏现在必须是Personal Access Token而不是账号密码直接填GitHub密码会报认证失败。这个细节放到报错章节细说。3.2 clone命令执行后日志到底在说什么在Git Bash里执行git clone https://github.com/octocat/Hello-World.git正常情况下会看到一串日志Cloning into Hello-World... remote: Enumerating objects: 16, done. remote: Counting objects: 100% (16/16), done. remote: Compressing objects: 100% (11/11), done. Receiving objects: 100% (16/16), 4.52 KiB | 1.13 MiB/s, done. Resolving deltas: 100% (1/1), done.我来解读一下这几行分别代表什么Cloning into Hello-World...本地创建目录并初始化仓库目录名默认取仓库名。remote: Enumerating objectsgit与GitHub服务器建立连接后服务器端在枚举仓库里有哪些对象commit、tree、blob。remote: Counting objects和remote: Compressing objects服务器端在统计对象数量并做压缩打包。Receiving objects本地正在接收数据包后面带的速度是实时传输速度这一行最直观地反映了网速。Resolving deltas本地接收完数据后根据增量差异重建完整的文件内容。只要最终没有fatal开头的报错且能回到光标提示符就说明clone成功了。很多人第一次看到中间卡住就以为死机了其实是仓库大、传输慢可以观察Receiving objects的百分比是否在动。3.3 克隆到指定目录、浅克隆与按需克隆有时候不想让项目目录就叫仓库名可以指定本地目录名git clone https://github.com/octocat/Hello-World.git my-project这样代码会放到my-project文件夹里。遇到超级大的仓库比如某些几十GB的代码库直接完整clone又慢又占磁盘。两个实用参数能救命git clone --depth 1 https://github.com/octocat/Hello-World.git--depth 1是浅克隆shallow clone只拉取最新一次提交的代码快照和它的文件内容不拉取历史版本。这个操作能让clone速度提升一个量级代价是不会获得git log的完整历史。对于只需要看当前代码、跑通项目的场景非常合适。还有一个更高阶的git clone --filterblob:none https://github.com/octocat/Hello-World.git这是按需克隆partial clone它先拉取所有提交记录和目录结构但每个文件的实际内容blob对象在checkout时才按需下载。对大仓库、低带宽场景体验很好尤其是你只需要仓库里部分目录的代码时。3.4 clone完成后的一系列验证操作克隆完别急着跑先花十秒确认环境就绪。进入项目目录cd Hello-World ls -la git log --oneline git status git remote -vls -la确认文件都在同时能看到隐藏的.git目录。没有.git目录意味着这不是git仓库之前的clone实际失败了。git log --oneline看提交历史是否能正常显示。浅克隆只有一条记录属正常。git status正常应该提示On branch main或On branch master工作区干净。git remote -v显示远程仓库地址确认origin指向的确实是GitHub上的地址。Windows下还有一个绕不开的问题路径过长。clone的仓库里嵌套目录结构很深时文件操作可能报filename too long。解决办法是开启Git的longpaths支持git config --global core.longpaths true同时需要在Windows系统设置里启用长路径支持组策略或注册表开启LongPathsEnabled两边都开了才能彻底解决。4. git clone卡住的常见网络原因与可落地的解法4.1 先定位是DNS、是TLS、还是连接超时git clone卡在某个阶段不动或者直接报Failed to connect、Connection timed out这是Windows用户在国内网络环境下最常遇到的场景。遇到这种情况别急着反复重试先判断是哪一层的故障。用浏览器打开github.com分三种情况浏览器也打不开说明是访问链路的问题DNS解析或出口节点可能被干扰看4.2。浏览器能打开但git clone超时说明TCP 443端口或TLS握手阶段被处理了看4.3和4.4。浏览器和git都正常只是速度慢这种是带宽问题调整git的传输相关配置可以缓解比如禁用HTTP/2。有一个检测TLS握手的好命令比ping可靠得多git ls-remote https://github.com/octocat/Hello-World.git这个命令只做远端查询不下载实际文件。如果它能快速返回引用的分支列表说明链路完全没问题问题出在后续的数据传输如果它都卡住或报超时那就是链路问题。4.2 修改DNS解析与刷新DNS缓存nslookup github.com是第一个该执行的命令。如果能看到IP地址但浏览器访问还是一直转圈或者解析出来的IP明显异常比如非GitHub的IP段那你所在环境的DNS服务器可能返回了不可用的解析结果。换公共DNS是有效的解法。Windows下修改DNS的操作路径控制面板 - 网络和 Internet - 网络连接 - 右键当前网卡 - 属性 - 双击Internet协议版本4TCP/IPv4 - 使用下面的DNS服务器地址。填入首选 DNS 服务器223.5.5.5 备用 DNS 服务器114.114.114.114这是国内两个长期稳定的公共DNS服务。改完执行ipconfig /flushdns刷新DNS缓存再跑一次nslookup github.com验证解析。需要提醒的是有时候直接改DNS不一定能完全解决因为问题可能出在更上层的连接被限速。DNS是排查第一步不是万能药。4.3 官方链路外的几种加速思路Gitee导入与Release压缩包如果GitHub官方链路的访问持续不稳定我建议换一条国产链路用Gitee码云的仓库导入功能。操作很直观Gitee右上角号里选从GitHub/GitLab导入仓库粘贴GitHub仓库地址Gitee服务器会从GitHub拉取一份镜像到Gitee之后你从Gitee直接clone。因为Gitee服务器在国内clone速度通常能达到几MB/s甚至几十MB/s。这个方案的优点是完全合法、免费、官方支持不用折腾任何网络工具。缺点是导入的是某个时间点的快照GitHub源仓库后续的更新Gitee这块镜子不会自动同步。你自己可以再手动导入一次来更新或者把Gitee仓库和GitHub仓库都配置为remote后面用git pull gitee main拉国内镜像、用git push origin main推GitHub正式分支两边互通。另外还有一个经常被忽略的思路很多项目在GitHub的Release页面提供了编译好的压缩包.zip/.tar.gz。如果你只需要用成品而不需要源代码和提交历史直接在Release里下载压缩包是速度最快的方式。压缩包由GitHub的CDN分发走Release下载往往比走git协议快很多。社区里也有不少长期维护的GitHub加速代理服务clone公共仓库时可以了解但涉及私有仓库、涉及账号密码的操作不建议走任何第三方服务存在安全隐患。4.4 公司网络代理的git配置写法如果你所在的公司或学校网络本身配备了HTTP代理比如访问外网必须走某个代理地址git默认是不走代理的需要显式告诉它git config --global http.proxy http://代理地址:端口 git config --global https.proxy http://代理地址:端口有些代理还要带账号密码http://用户名:密码代理地址:端口。代理配置支持细粒度控制只让github.com走代理其他仓库不走git config --global http.https://github.com/.proxy http://代理地址:端口这样配置最稳妥既不影响访问国内代码托管平台的速度也不用担心全局代理把所有流量都导过去。还有一个弱网环境下非常实用的小技巧。git默认有一个低速超时机制如果传输速度持续低于http.lowSpeedLimit且持续时间超过http.lowSpeedTime秒git会主动断开连接。在带宽不稳定的网络里这很坑大仓库拉到一半被掐断。把它关掉git config --global http.lowSpeedLimit 0 git config --global http.lowSpeedTime 9999995. 几个高频clone报错的完整排查记录5.1 active post-checkout hook found虚惊一场有很多Winodws用户在clone时见过这样一行提示active post-checkout hook found during git clone: c:/users/xxx/devecos第一次遇到时以为克隆失败了其实不是。这个提示说明在clone完成后的post-checkout阶段git检测到了.git/hooks/post-checkout文件执行了里面配置的钩子脚本。钩子文件哪来的通常是你机器上安装的某些开发工具或编辑器扩展在初始化仓库时注入的用于自动执行格式化、代码检查之类的工作。处理方式很直接进入项目目录的.git/hooks文件夹看到post-checkout文件用文本编辑器打开看一眼内容。如果确认是不认识的脚本直接删掉或重命名为post-checkout.bak禁用。这个文件只是影响git的钩子触发与项目源码完全无关删了不影响仓库任何功能。5.2 no support authentication认证方式不兼容报错长这样fatal: unable to access https://github.com/xxx/xxx.git/: no support authentication这个报错在Windows上比较常见核心原因是git找不到可用的凭据管理器来缓存和提供认证信息。默认安装的Git for Windows虽然自带Git Credential Manager但可能没被正确启用。解法是在全局配置里指定凭据助手git config --global credential.helper manager-core新版Git2.39及以上用的是manager老版本用manager-core。配置完之后再clone弹出让你登录GitHub的窗口时正常登录凭据就会被缓存下来。如果密码那栏一直报错去GitHub的Settings - Developer settings - Personal access tokens里生成一个新的token作为密码输入即可账号主页的密码现在不能用于git操作了。5.3 unable to access与Operation timed out链路问题最常见的报错组合是fatal: unable to access https://github.com/xxx/xxx.git/: Failed to connect to github.com port 443: Timed out这种超时和你的git命令没有关系是本地到github.com:443的网络链路不通。按第四章的方法排查先跑git ls-remote确认链路状态再看DNS解析最后考虑Gitee导入等替代方案。过程中注意一个细节不要用ping github.com来测github.com的服务器对ping协议ICMP处理不友好大概率超时容易误判。git ls-remote是验证链路最贴近实际的方式因为它走的就是HTTPS 443端口跟clone的路径一致。5.4 克隆中断后如何断点续传git clone本身没有原生的断点续传功能下载到一半断了重新执行clone又从头开始这对大仓库来说是灾难。实际操作中有个曲线救国的方案利用git的增量拉取能力。先初始化一个空仓库并关联远端git init my-project cd my-project git remote add origin https://github.com/xxx/xxx.git git fetch --depth1 origin maingit fetch注意不是clone会尝试从上次断点继续拉取对象如果网络没完全断反复执行几次git fetch是可以把数据补齐的。fetch完成后git checkout -b main FETCH_HEAD就能切出一个包含完整文件的工作分支。这个方法特别适合浅克隆大仓库做到90%被掐断的场景。6. clone不是终点拉下来的项目怎么用起来6.1 查看分支状态与切换分支clone完成以后你的本地仓库默认在默认分支上通常是main或master远端所有分支也已经被git记录在案。用git branch -a查看$ git branch -a * main remotes/origin/HEAD - origin/main remotes/origin/dev remotes/origin/mainremotes/origin/dev就是远端分支。要切到开发分支用git switch dev新版命令或git checkout dev老命令都可以。切过去之后本地会自动创建一条与origin/dev关联的同名分支。这是clone之后最高频的操作项目一般不会只留一个主分支。6.2 拉取远端更新pull与fetch的区别项目在GitHub上被别人更新了你想同步最新代码。两个命令看起来差不多其实逻辑不同git fetch只是把远端的最新提交拉取到本地的origin/xxx引用里不修改工作区文件。git pull相当于git fetch加git merge两步会直接合并到当前分支并更新工作区。对新手来说直接git pull最直观。但注意一点如果你本地有未提交的修改pull时产生了冲突git会先拒绝合并并提示你处理冲突。此时先git status看冲突文件手动解决后git add和git commit完成合并即可。6.3 大文件仓库与.gitignore的配合有些仓库体积大是因为一直在跟踪大文件模型权重、素材包、二进制文件等。Git LFSLarge File Storage是GitHub应对大文件的官方方案仓库里可能配了.gitattributes文件重定向指针。clone这种仓库需要本地装好LFS插件否则拉下来的是几十字节的指针文件而不是真实内容git lfs install git lfs pull再说.gitignore。它决定哪些文件不进入版本控制clone下来的仓库里如果已经有这个文件说明作者已经预设了忽略规则。你自己新建项目时也应该创建它把编译产物node_modules、bin、obj、IDE配置.idea、.vscode、日志文件等都忽略掉。Windows用户特别要注意把系统产生的Thumbs.db这类文件加进去避免把无关文件提交到仓库。6.4 从零到一的一个完整工作流把前面所有内容串起来一个完整的Windows下单仓库工作流大概是这样的安装Git做完基础配置user.name、user.email、core.autocrlf、init.defaultBranch。在GitHub找到目标仓库复制HTTPS地址。Git Bash里执行git clone观察日志传递是否正常。进入项目目录git branch -a确认分支情况。按需切换分支安装依赖、运行项目。修改代码后git status查看改动git add、git commit提交到本地git push推回远程。这套流程走顺了Git工具链在日常开发中的价值才算真正发挥出来。Windows环境下的坑主要集中在安装配置、行尾符、网络链路三个区域提前把预防工作做完后续的clone体验会顺畅很多。我在Windows上折腾Git踩过的坑基本都在这了如果按这个流程走一遍应该能少走不少弯路。