直接跟新手说结论在 Windows 上把 Git 装好、配好、SSH 打通是每一个开发者绕不过去的第一道坎。很多人卡在的不是 Git 本身而是装完之后一脸懵——环境变量是干吗的为什么每次 push 都要输密码SSH key 到底是什么这篇文章我会把从零到一的全过程拆开揉碎包括版本选择、每一步勾选的理由、密钥生成的原理、常见报错的排查尽量让你看完之后能独立搞定而不是照着别人的截图机械操作。1. 整体思路设计与下载准备1.1 为什么需要一套完整的安装配置流程工作里最常见的场景是入职新公司、重装系统、换新电脑然后要在 Windows 上把开发环境盘活。绝大多数教程只讲“下一步下一步”不讲为什么这么点、那些选项到底影响了什么。结果就是出了问题不知道怎么排查。比如最常见的一个现象Git 明明装好了VSCode 里也认出来了但一推代码就卡在输密码或者干脆报“Permission denied (publickey)”。这里的关键在于Git 的安装只是第一步真正起作用的是安装后的三件事环境变量是否正确注册、全局用户信息是否匹配、SSH 密钥是否成功信任。这三件事没打通后面所有操作都会磕磕绊绊。1.2 官方版本与非官方版本的选择思路下载 Git 时最稳妥的选择是去 Git 官网也就是 git-scm.com点 Downloads页面会自动识别 Windows 系统。需要说清楚的是官网下载的是 Git for Windows这是一个基于 MSYS2 环境的完整发行版除了 Git 本体之外还自带了一堆 Unix 小工具比如 bash、ssh、grep、sed这也是为什么装完 Git 之后你可以在 Git Bash 里用很多 Linux 命令。国内用户可能会遇到官网下载慢的问题可以考虑使用国内镜像源比如阿里云、清华 TUNA、华为云都有对应的 Git for Windows 镜像版本更新可能比官网慢一两天但安全性没有问题。我个人的建议是优先官网下载慢就用镜像但一定不要随便在一个不知名博客里点“高速下载”按钮那些基本都捆绑了推广软件。1.3 安装前需要确认的系统环境安装之前建议先确认两件事。第一Windows 版本和系统架构。Git for Windows 分 64 位和 32 位现在的机器基本都是 64 位检查方法是右键“此电脑”选“属性”或者在 PowerShell 里输入echo $env:PROCESSOR_ARCHITECTURE输出 AMD64 就是 64 位。第二当前系统是否有未保存的工作。虽然 Git 安装不需要重启但安装过程中如果杀毒软件或安全策略拦截可能会卡住建议先把安全软件临时关掉或者至少放行安装程序。提示如果你在公司电脑上安装可能没有管理员权限。Git for Windows 其实可以在用户级安装不一定非要管理员但某些写入系统盘的组件比如 Shell 集成会失败这一点后面会讲到。2. Git 下载与安装详解2.1 下载时如何判断选择哪个版本官网下载页会显示最新的 Windows 版本通常有两个选择64-bit Git for Windows Setup 和 32-bit Git for Windows Setup。除此之外你还会看到 Portable 版本和 MinGit 版本。Portable 版是便携版解压即用不写入注册表适合放在 U 盘或者临时环境配置是独立保存的不参与系统级联动的场景下用很方便但我个人不太建议新手用因为会带来环境变量和路径解析的额外麻烦。MinGit 则是嵌入式精简版只包含核心 Git 命令行工具是给 IDE 或者编辑器内置集成用的比如 VSCode 在某些情况下会通过内置的 MinGit 来提供 Git 支持但它不包含 Git Bash也不适合作为日常主力工具。对大多数开发者来说下载 64 位 Setup 版就够了。下载完成后你会得到一个类似Git-2.47.1-64-bit.exe的安装包双击运行一路往下走但有几个安装界面的选项我得单独拉出来讲因为新手往往是在这里埋下的坑。2.2 安装界面各选项的含义与推荐选择安装向导的第一个关键选项是 “Select Components”。这里有Additional icons桌面图标、Windows Explorer integration右键菜单集成、Git LFS大文件存储、Associate .git* configuration files with default text editor关联 .git 配置文件到默认编辑器、Associate .sh files to be run with Bash关联 .sh 文件到 Bash等。我的建议是附加图标可装可不装对操作没影响。Windows Explorer integration 推荐勾选因为右键“Git Bash Here”和“Git GUI Here”这两个入口太常用了尤其是 Git Bash Here能直接在当前目录打开命令行省去手动 cd 的麻烦。Git LFS 建议勾选现在很多项目仓库里会涉及到大文件管理硬编码大文件直接推到 Git 会把仓库撑爆LFS 是官方解决方案提前装好后面不用再补。“Associate .git* configuration files” 建议选Use Notepad或Use Visual Studio Code如果检测到了的话但默认的 Vim 对新手简直是灾难——敲:q!退出把很多人直接劝退。如果你还不确定选Use Visual Studio Code最稳妥没有的话就接受默认Vim也行我们后面会讲改默认编辑器的方法。第二个关键界面是 “Choosing the default editor used by Git”。这里默认是 Vim但绝大多数 Windows 用户没接触过 Vim我强烈建议改成 VS Code、Notepad 或者任何你熟悉的文本编辑器。这个改动会写入 Git 的配置项core.editor省得后面在命令行里写 commit message 时一进 Vim 就不知道怎么保存退出。第三个关键界面是 “Adjusting your PATH environment”。翻译成人话就是装完之后你在 CMD 或者 PowerShell 里输入git能不能直接被系统找到。这里默认的选项是 “Git from the command line and also from 3rd-party software”这个选项会把 Git 的可执行文件路径写入系统 PATH 环境变量推荐保持默认。如果你选了 “Use Git from Git Bash only”那 CMD 和 PowerShell 里就找不到 git 命令会有各种莫名其妙的问题。记住这里一定选中间那个。第四个关键界面是 “Choosing HTTPS transport backend”。这里有两个选项Use the OpenSSL library和Use the native Windows Secure Channel library。前者是 Git 内部捆绑的 OpenSSL兼容性更广证书验证行为在所有平台上是一致的后者用的是 Windows 自带的证书库好处是企业内网 SSL 证书比如公司自己签发的证书能被系统自动信任少配些麻烦但不同机器的行为可能不一致。没有企业内网特殊要求的话保持默认 OpenSSL 就行。第五个关键界面是 “Configuring the line ending conversions”。这可能是新手最疑惑的地方了。这里给三个选项Checkout Windows-style, commit Unix-style line endingsCheckout as-is, commit Unix-style line endingsCheckout as-is, commit as-is默认选第一个。原因是 Git 的祖先是在 Unix 世界里诞生的它内部存储文本文件统一用 LF换行符是\n但 Windows 原生习惯用 CRLF回车加换行\r\n。选第一个意味着 checkout 时把 LF 转成 CRLFcommit 时把 CRLF 转回 LF这样会让 Windows 下的编辑器打开时体验正常显示为 Windows 换行交到仓库里的文件又是规范的 Unix 风格。如果项目里已经存在大量 CRLF 文件或者你主要在 Windows 上写跨平台脚本这个选项会减少一堆诡异的“文件全部被修改”问题。第六个关键界面是 “Configuring the terminal emulator to use with Git Bash”。这里默认是 MinTTY推荐保持默认。MinTTY 支持更丰富的终端交互比如快捷键、颜色渲染都要好一些。另一个选项是 Windows 系统自带的 Console Window如果你习惯了 CMD 的外观也可以选但实际体验差不少。这个问题不大后面还可以通过各种方式调整。第七个界面是 “Configuring extra options”——主要是Enable file system caching和Enable symbolic links。文件系统缓存建议勾选能有效提升 Git 在大仓库下的性能。符号链接的启用取决于你是否需要在 Windows 上创建和管理符号链接如果项目依赖 Unix 符号链接特性比如 monorepo 中用 symlink 组织包可以勾上但需要注意 Windows 上创建符号链接需要管理员权限开了之后实际操作还有一坑新手暂时可以不勾。安装完成后建议打开 CMD 或 PowerShell输入以下命令验证安装git --version如果输出类似git version 2.47.1.windows.1说明安装成功且 PATH 配置正确。如果提示“git 不是内部或外部命令”那就是 PATH 没生效需要手动检查环境变量。3. 基础环境配置与细节打磨3.1 用户身份配置这一步决定你的提交记录装好 Git 之后先配置用户名和邮箱这一步非常关键。Git 每次 commit 都会记录这两个信息如果没配置提交时 Git 会用系统主机名生成看起来非常奇怪的身份也可能会直接拒绝。打开 Git Bash执行git config --global user.name 你的名字 git config --global user.email 你的邮箱这里的--global表示全局生效针对当前系统用户的所有仓库。如果你想对某个仓库单独设置身份可以去掉--global在该仓库目录下执行git config user.name和git config user.email。这个场景在同时使用公司 Git 和个人 Git 时很常用比如公司仓库用公司邮箱个人开源项目用 Gmail。配置完之后可以查看一下当前所有配置git config --list注意邮箱最好和你的代码托管平台GitHub、GitLab、Gitee注册邮箱保持一致这样提交记录的头像才能正确关联。如果你特别在意邮箱隐私GitHub 支持开启 “Keep my email addresses private”会给你一个类似xxxxxusers.noreply.github.com的匿名邮箱那个也可以拿来配 Git只是在团队内部协作时别人看提交记录找到的就不是你的真实邮箱了。3.2 默认分支名、换行符与代理配置Git 默认分支名是master但近年来主流平台新建仓库时默认分支已经是main。为了保持一致避免本地仓库和远程仓库默认分支不一样导致的上传时分支名冲突建议统一设置git config --global init.defaultBranch main这样你在任何地方执行git init默认分支就是 main。这里多说一句分支名本身没有魔法叫什么都行main只是当前社区约定俗成的选择。换行符的配置在安装时已经处理过但如果你用了其他工具改过也可以通过命令来修正git config --global core.autocrlf true在 Windows 上true表示 checkout 时转成 CRLFcommit 时转回 LFLinux 和 macOS 上通常设成input也就是保留原样仅在提交时转 LF。代理配置是另一个很容易踩坑的点。如果你是公司网络或者本地开了代理工具HTTP 和 HTTPS 代理可以这样配置git config --global http.proxy http://127.0.0.1:7890 git config --global https.proxy http://127.0.0.1:7890假设代理端口是 7890 就填 7890实际端口以你的代理工具为准。配置完成后clone 和 fetch 都会走代理速度会有明显提升。不想要的时候删除配置git config --global --unset http.proxy git config --global --unset https.proxy有些同事的仓库走的是 SSH 协议SSH 的代理是独立配置的后面讲 SSH 时会提到。3.3 解决 Git 终端乱码与 commit message 编辑器问题Windows 上 Git 的乱码问题几乎是必现的尤其是在 Git Bash 里查看中文文件名、中文 commit message、或者执行git log时显示成\354\227\254\352\270...这样的转义序列。这个问题的根源是 Git 在 Windows 上的编码识别默认不是 UTF-8。在 Git Bash 里直接修改全局配置可以解决git config --global core.quotepath false git config --global gui.encoding utf-8 git config --global i18n.commit.encoding utf-8 git config --global i18n.logoutputencoding utf-8core.quotepath false是最重要的一行它让 Git 在显示中文文件路径时直接显示中文而不是用八进制转义序列。另外三个配置保证提交信息读取和输出时统一走 UTF-8。如果你在 Git Bash 里运行git log输出的中文还是乱码可以再试一下在 Bash 里执行export LESSCHARSETutf-8这个环境变量影响的是less分页器的编码。Git 默认用 less 来分页显示 log 输出它按自己的字符集去解码不设对就会乱。commit message 编辑器的问题前面铺垫过了如果不小心选成了 Vim 或者后来想换命令是这样git config --global core.editor code --waitcode --wait是 VS Code 的命令行参数意思是 Git 调用编辑器时打开 VS Code 并等待你关闭文件后再继续执行。在 Windows 上这个配置会按引号里的命令找到 VS Code 的可执行文件。如果没有用 VS Code也可以改成notepad或notepad的路径。这个不复杂但能救回很多对着 Vim 不知道按哪个键的同学。4. SSH 密钥配置与远程仓库免密连接4.1 SSH 协议和 HTTPS 协议的区别和选择远程仓库连接有两种主流方式HTTPS 和 SSH。HTTPS 的方式最直接clone 时直接填仓库地址推送的时候输入用户名密码或者 Personal Access TokenPAT。这种方式的主要问题是每次 push 都要输凭证或者需要依赖 Windows 凭据管理器去记住密码。在 GitHub 上HTTPS 密码早已失效必须使用 PAT而 PAT 像一串很难记的长随机数往密码框里粘贴时还特别容易出错。SSH 的方式则属于公钥加密通信。你生成一对密钥私钥留在本地公钥填到代码托管平台的 SSH Keys 设置里。之后每次 Git 通过 SSH 协议连接远程仓库时服务器用公钥验证你的身份本地私钥自己保管整个过程免密、安全而且没有 HTTPS 那种临时密码过期的问题。对于日常开发来说SSH 是效率最高、最省心的方案。下面就从生成密钥开始把整个流程走一遍。4.2 生成密钥对实操步骤与参数解释打开 Git Bash执行ssh-keygen -t ed25519 -C 你的邮箱或备注这里我用了ed25519而不是更老的 RSA。ed25519 是更现代的椭圆曲线签名算法密钥更短、生成更快、安全性也足够。如果你的 Git 托管平台或者服务器不支持 ed25519极少见老旧的 GitLab 自建实例可能有这个情况可以退一步用ssh-keygen -t rsa -b 4096 -C 你的邮箱或备注-t指定算法类型-b指定位长RSA 的话 4096 位是当前推荐的最低强度。ed25519 不需要-b参数因为它的密钥长度是固定的。执行过程中会询问保存位置默认在~/.ssh/id_ed25519这里建议保持默认。接着会让你设置 passphrase这一步其实是给你的私钥再加一把锁就算有人拿到了你的私钥文件没有 passphrase 也无法使用。如果你嫌每次用 key 都要输密码麻烦可以留空直接回车如果想要更安全但又能省去每次输入的麻烦可以配合 ssh-agent 来做后面会讲。生成完成后用下面的命令查看公钥cat ~/.ssh/id_ed25519.pub公钥是一串ssh-ed25519 一大段字符串 你的邮箱格式的文本把它完整复制下来一会儿要填到平台里。4.3 将公钥配置到 GitHub、GitLab、Gitee以 GitHub 为例登录 GitHub 后依次进入 Settings → SSH and GPG keys → New SSH key。Title 可以填My Windows PC或者任何你能认出来的名字便于以后管理多台设备时区分。Key 那一栏粘贴刚才复制的公钥内容保存即可。Gitee 的操作是头像下拉菜单 → 设置 → 安全设置 → SSH 公钥GitLab 则是在 Preferences → SSH Keys。三个平台本质相同都是把你的公钥文本放进平台的白名单里。配置完之后测试一下连接ssh -T gitgithub.com看到类似Hi username! Youve successfully authenticated, but GitHub does not provide shell access.就说明密钥已经生效。Gitee 的测试地址是ssh -T gitgitee.comGitLab 需要根据你自己的域名走比如ssh -T gitgitlab.example.com。这个测试相当于一次握手验证服务器告诉你“我认出你是谁了但我不给你 shell 环境”正常的不是报错。4.4 ssh-agent 与私钥管理多密钥场景下的最佳实践如果你只有一台电脑、一套密钥上面的配置已经够用了。但一个很现实的场景是个人电脑同时要连 GitHub、公司 GitLab甚至可能还有客户服务器的 SSH。多套密钥的时候如果每个密钥都叫id_ed25519会互相覆盖。更好的习惯是给不同用途的密钥命名比如ssh-keygen -t ed25519 -C work email -f ~/.ssh/id_ed25519_work ssh-keygen -t ed25519 -C personal email -f ~/.ssh/id_ed25519_personal使用的时候通过 SSH 配置文件~/.ssh/config来指定不同主机使用哪个密钥Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_personal Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_work这样当你 clone 或者 push 到不同平台时Git 会自动根据 Host 匹配对应的私钥不需要每次手动指定。ssh-agent 的作用是替你保管已经解锁的私钥这样使用带 passphrase 的密钥也能做到一次输入、会话内免密。常见的启动方式是eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519第一条命令启动 ssh-agent 后台进程并设置好环境变量第二条命令把私钥加入当前会话。之后在这个会话内再用同一密钥就不会再提示输入 passphrase。Windows 上如果你装了 Git for WindowsSSH 相关的工具是自带的不需要额外安装任何东西。如果你用的是原生 OpenSSHWindows 10 1809 之后系统自带可能在服务和密钥权限上有细微差异但只要测试通了就不需要关心底层用的是哪套 SSH 实现。5. 常见问题与排查技巧实录5.1 高频报错速查表我把这些年遇到过的高频问题做成一个表方便你直接对照排查。问题现象常见原因解决办法git不是内部或外部命令安装时 PATH 没选对或环境变量没刷新重新执行安装程序修改 PATH或手动将C:\Program Files\Git\cmd加入系统 PATHclone/push 时反复要求输密码远程地址用的是 HTTPS或 SSH 密钥没配置成功改用 SSH 地址从https://github.com/...换成gitgithub.com:...Permission denied (publickey)公钥没加进平台或本机自动使用了错误的私钥检查ssh -T gitgithub.com输出确认公钥已添加必要时配置~/.ssh/config指定密钥git commit时进入 Vim 无法退出默认编辑器是 Vim新手不知道命令按Esc输入:wq回车保存退出或重新配置core.editor中文文件名变成\345\233\276\347\211\207core.quotepath默认为 true执行git config --global core.quotepath falsefatal: Not a git repository当前目录不在仓库内先执行git init或cd进入仓库目录src refspec main does not match any本地还没有任何提交空仓库推送先git add和git commit之后再 pusherror: failed to push some refs远程仓库有本地没有的提交先git pull --rebase拉取合并再 pushGit 操作极慢、卡在连接网络问题或代理配置不正确重新配置http.proxy与https.proxy或者关掉代理The file will have its original line endings警告换行符转换行为与仓库现状不一致检查core.autocrlf设置与团队约定统一5.2 密钥权限错误这个报错在 Windows 上尤其迷惑如果你在 SSH 连接时看到Permissions for C:\\Users\\xxx/.ssh/id_ed25519 are too open.这是 SSH 在检查私钥文件权限时发现文件权限过于宽松出于安全考虑直接拒绝了。这个报错在 Linux 上很常见因为默认 umask 可能放开了其他用户读权限Windows 上的触发场景不太一样——通常是私钥文件从别处复制过来或者通过某些同步工具同步下来导致文件 ACL 权限继承了不正确的用户组。解决办法是右键私钥文件 → 属性 → 安全 → 高级 → 禁用继承 → 将继承的权限转换为显式权限 → 移除除了当前用户之外的所有条目最后保证当前用户有完全控制权限其他用户全部删除。改完这个再执行一次ssh -T gitgithub.com验证。5.3 清除错误记住的凭据与缓存如果你的电脑以前用 HTTPS 方式连过远程仓库Windows 凭据管理器里会缓存用户名和密码或者 PAT。后来你切换成 SSH 方式却发现 Git 仍然尝试用 HTTPS 凭证可能是因为该仓库的 remote 地址还是 HTTPS 的。先看一下当前仓库的远程地址git remote -v如果是https://github.com/...把它改成 SSHgit remote set-url origin gitgithub.com:username/repo.git如果凭据管理器里存了错误的 PAT 导致推送失败可以在 Windows 的“控制面板 → 用户账户 → 凭据管理器”里找到git:https://github.com条目直接删除下次连接时会重新要求输入或者干脆换 SSH 地址一劳永逸。5.4 远程仓库分支名不匹配时的处理新建远程仓库时如果平台默认分支是 main而你本地按旧习惯用 master推送时会提示分支不存在。常见做法是先把本地分支改名git branch -M main-M强制改名不管当前分支是否叫 master 都能改成 main。改完之后再git push -u origin main这样本地 main 分支就和远程 main 建立了跟踪关系。如果你还没有任何提交远程是空仓库可以直接git init git add . git commit -m first commit git branch -M main git remote add origin gitgithub.com:username/repo.git git push -u origin main这套流程能避免 90% 的新手刚创建仓库时的报错。6. 日常使用中值得养成的几个习惯6.1 提交前检查变更内容很多初学者喜欢git add .一把梭然后直接 commit。这个习惯很危险因为会把临时文件、编译产物、密钥文件不小心提交进去而且一旦提交上去再清理历史会非常痛苦。建议提交前先git status git diff查看被修改的文件列表以及具体的改动内容。如果文件太多可以用git diff --stat先看统计觉得没问题再git status确认全部文件都是想要提交的。这个习惯能帮你提前拦截掉一大堆不该提交的东西。6.2 .gitignore 要在一开始就配好新建仓库时最值得花十分钟做的就是写好.gitignore。不同语言和工具链的通用模板可以从 GitHub 的 gitignore 仓库里找比如Windows、VisualStudioCode、Node、Python这些模板都已经维护得很完善。如果你不确认某个路径该不该忽略遵循一个简单原则能生成出来的文件、包含密钥或密码的文件、个人本地配置文件比如 IDE 的工作区文件都该忽略。有个常见的反例是某同事把项目整个node_modules目录提交到了 Git 仓库结果 clone 下来后发现仓库体积巨大操作卡成幻灯片。这个问题通过事后清理也能解决但让所有参与项目的人心累不如一开始就拦住。就算不慎提交了也不要乱删历史优先是添加到.gitignore再让远程仓库同步忽略。6.3 多用 fetch 而不是直接 pull团队协作时每次开工前先git fetch一下看看远程有没有新的分支和提交。git fetch只下载远程数据不会改动你当前的工作区没有副作用而git pull默认会进行一次 merge如果你的工作区有未提交的修改可能会引发冲突。我自己的习惯是开工前先看一眼git fetch --all --prune git status--prune会清理本地已经删除的远程分支的引用保持远程跟踪列表干净。看到远程有哪些变化后再决定是 merge、rebase 还是直接切分支。这个习惯比直接git pull安全很多尤其是多人协作、分支复杂的项目里能少踩好多坑。6.4 报错信息要完整拍下来或者复制原文排查 Git 问题最忌讳只截个“它报错了”的图却不带完整报错文本。Git 的报错信息很长但很多关键线索就在最后几行。比如fatal: unable to access https://...: OpenSSL SSL_read: Connection was reset, errno 10054这个报错意味着访问远程地址时连接被重置可能是网络代理、防火墙或者中间设备拦截导致的。如果只看前半句“unable to access”就很容易被误导到权限方向白白浪费排查时间。解决问题时把完整的报错文本复制到搜索引擎、或者发给同事得到的答案准确率会高很多。这也是我常年建议新人的一个习惯报错信息全文优先截图其次不要只描述“我 push 失败了”这种没有信息量的话。7. 最后分享两点个人经验如果你照着教程走到了这一步Git 的安装、配置和 SSH 密钥应该已经全部打通。最后分享两个我在实际工作中觉得非常重要的细节。第一私钥一定不要上传到任何网盘、代码仓库、聊天工具里。私钥是你身份的证明拿到私钥等于拿到你代码仓库的访问权限。如果你怀疑私钥泄漏立刻在托管平台删除对应公钥、重新生成一对新的然后删掉本地旧的私钥文件。这个操作成本很低但很多人会拖直到出现安全问题才后悔。第二Git 的配置文件是可迭代的。今天配了core.autocrlf明天可以加init.defaultBranch后天还能加自定义别名。比如给常用命令设置简写git config --global alias.st status git config --global alias.co checkout git config --global alias.br branch git config --global alias.lg log --oneline --graph --all --decorate之后输入git st、git co、git lg会比完整命令快不少。但要注意别名只是你本地的行为不会影响别人看你的提交所以放心大胆地改。Git 的配置文件本质上是跟随你个人的重点是你清楚每一项的含义而不是盲目复制别人的配置。我在实际换过几次电脑之后最大的感受是第一次配置 Git 环境时把这些底层逻辑搞清楚后面每次换设备都只是重复劳动不会有任何障碍。希望这篇教程能帮你把这一步走扎实。
Windows下Git安装配置与SSH密钥设置全攻略
直接跟新手说结论在 Windows 上把 Git 装好、配好、SSH 打通是每一个开发者绕不过去的第一道坎。很多人卡在的不是 Git 本身而是装完之后一脸懵——环境变量是干吗的为什么每次 push 都要输密码SSH key 到底是什么这篇文章我会把从零到一的全过程拆开揉碎包括版本选择、每一步勾选的理由、密钥生成的原理、常见报错的排查尽量让你看完之后能独立搞定而不是照着别人的截图机械操作。1. 整体思路设计与下载准备1.1 为什么需要一套完整的安装配置流程工作里最常见的场景是入职新公司、重装系统、换新电脑然后要在 Windows 上把开发环境盘活。绝大多数教程只讲“下一步下一步”不讲为什么这么点、那些选项到底影响了什么。结果就是出了问题不知道怎么排查。比如最常见的一个现象Git 明明装好了VSCode 里也认出来了但一推代码就卡在输密码或者干脆报“Permission denied (publickey)”。这里的关键在于Git 的安装只是第一步真正起作用的是安装后的三件事环境变量是否正确注册、全局用户信息是否匹配、SSH 密钥是否成功信任。这三件事没打通后面所有操作都会磕磕绊绊。1.2 官方版本与非官方版本的选择思路下载 Git 时最稳妥的选择是去 Git 官网也就是 git-scm.com点 Downloads页面会自动识别 Windows 系统。需要说清楚的是官网下载的是 Git for Windows这是一个基于 MSYS2 环境的完整发行版除了 Git 本体之外还自带了一堆 Unix 小工具比如 bash、ssh、grep、sed这也是为什么装完 Git 之后你可以在 Git Bash 里用很多 Linux 命令。国内用户可能会遇到官网下载慢的问题可以考虑使用国内镜像源比如阿里云、清华 TUNA、华为云都有对应的 Git for Windows 镜像版本更新可能比官网慢一两天但安全性没有问题。我个人的建议是优先官网下载慢就用镜像但一定不要随便在一个不知名博客里点“高速下载”按钮那些基本都捆绑了推广软件。1.3 安装前需要确认的系统环境安装之前建议先确认两件事。第一Windows 版本和系统架构。Git for Windows 分 64 位和 32 位现在的机器基本都是 64 位检查方法是右键“此电脑”选“属性”或者在 PowerShell 里输入echo $env:PROCESSOR_ARCHITECTURE输出 AMD64 就是 64 位。第二当前系统是否有未保存的工作。虽然 Git 安装不需要重启但安装过程中如果杀毒软件或安全策略拦截可能会卡住建议先把安全软件临时关掉或者至少放行安装程序。提示如果你在公司电脑上安装可能没有管理员权限。Git for Windows 其实可以在用户级安装不一定非要管理员但某些写入系统盘的组件比如 Shell 集成会失败这一点后面会讲到。2. Git 下载与安装详解2.1 下载时如何判断选择哪个版本官网下载页会显示最新的 Windows 版本通常有两个选择64-bit Git for Windows Setup 和 32-bit Git for Windows Setup。除此之外你还会看到 Portable 版本和 MinGit 版本。Portable 版是便携版解压即用不写入注册表适合放在 U 盘或者临时环境配置是独立保存的不参与系统级联动的场景下用很方便但我个人不太建议新手用因为会带来环境变量和路径解析的额外麻烦。MinGit 则是嵌入式精简版只包含核心 Git 命令行工具是给 IDE 或者编辑器内置集成用的比如 VSCode 在某些情况下会通过内置的 MinGit 来提供 Git 支持但它不包含 Git Bash也不适合作为日常主力工具。对大多数开发者来说下载 64 位 Setup 版就够了。下载完成后你会得到一个类似Git-2.47.1-64-bit.exe的安装包双击运行一路往下走但有几个安装界面的选项我得单独拉出来讲因为新手往往是在这里埋下的坑。2.2 安装界面各选项的含义与推荐选择安装向导的第一个关键选项是 “Select Components”。这里有Additional icons桌面图标、Windows Explorer integration右键菜单集成、Git LFS大文件存储、Associate .git* configuration files with default text editor关联 .git 配置文件到默认编辑器、Associate .sh files to be run with Bash关联 .sh 文件到 Bash等。我的建议是附加图标可装可不装对操作没影响。Windows Explorer integration 推荐勾选因为右键“Git Bash Here”和“Git GUI Here”这两个入口太常用了尤其是 Git Bash Here能直接在当前目录打开命令行省去手动 cd 的麻烦。Git LFS 建议勾选现在很多项目仓库里会涉及到大文件管理硬编码大文件直接推到 Git 会把仓库撑爆LFS 是官方解决方案提前装好后面不用再补。“Associate .git* configuration files” 建议选Use Notepad或Use Visual Studio Code如果检测到了的话但默认的 Vim 对新手简直是灾难——敲:q!退出把很多人直接劝退。如果你还不确定选Use Visual Studio Code最稳妥没有的话就接受默认Vim也行我们后面会讲改默认编辑器的方法。第二个关键界面是 “Choosing the default editor used by Git”。这里默认是 Vim但绝大多数 Windows 用户没接触过 Vim我强烈建议改成 VS Code、Notepad 或者任何你熟悉的文本编辑器。这个改动会写入 Git 的配置项core.editor省得后面在命令行里写 commit message 时一进 Vim 就不知道怎么保存退出。第三个关键界面是 “Adjusting your PATH environment”。翻译成人话就是装完之后你在 CMD 或者 PowerShell 里输入git能不能直接被系统找到。这里默认的选项是 “Git from the command line and also from 3rd-party software”这个选项会把 Git 的可执行文件路径写入系统 PATH 环境变量推荐保持默认。如果你选了 “Use Git from Git Bash only”那 CMD 和 PowerShell 里就找不到 git 命令会有各种莫名其妙的问题。记住这里一定选中间那个。第四个关键界面是 “Choosing HTTPS transport backend”。这里有两个选项Use the OpenSSL library和Use the native Windows Secure Channel library。前者是 Git 内部捆绑的 OpenSSL兼容性更广证书验证行为在所有平台上是一致的后者用的是 Windows 自带的证书库好处是企业内网 SSL 证书比如公司自己签发的证书能被系统自动信任少配些麻烦但不同机器的行为可能不一致。没有企业内网特殊要求的话保持默认 OpenSSL 就行。第五个关键界面是 “Configuring the line ending conversions”。这可能是新手最疑惑的地方了。这里给三个选项Checkout Windows-style, commit Unix-style line endingsCheckout as-is, commit Unix-style line endingsCheckout as-is, commit as-is默认选第一个。原因是 Git 的祖先是在 Unix 世界里诞生的它内部存储文本文件统一用 LF换行符是\n但 Windows 原生习惯用 CRLF回车加换行\r\n。选第一个意味着 checkout 时把 LF 转成 CRLFcommit 时把 CRLF 转回 LF这样会让 Windows 下的编辑器打开时体验正常显示为 Windows 换行交到仓库里的文件又是规范的 Unix 风格。如果项目里已经存在大量 CRLF 文件或者你主要在 Windows 上写跨平台脚本这个选项会减少一堆诡异的“文件全部被修改”问题。第六个关键界面是 “Configuring the terminal emulator to use with Git Bash”。这里默认是 MinTTY推荐保持默认。MinTTY 支持更丰富的终端交互比如快捷键、颜色渲染都要好一些。另一个选项是 Windows 系统自带的 Console Window如果你习惯了 CMD 的外观也可以选但实际体验差不少。这个问题不大后面还可以通过各种方式调整。第七个界面是 “Configuring extra options”——主要是Enable file system caching和Enable symbolic links。文件系统缓存建议勾选能有效提升 Git 在大仓库下的性能。符号链接的启用取决于你是否需要在 Windows 上创建和管理符号链接如果项目依赖 Unix 符号链接特性比如 monorepo 中用 symlink 组织包可以勾上但需要注意 Windows 上创建符号链接需要管理员权限开了之后实际操作还有一坑新手暂时可以不勾。安装完成后建议打开 CMD 或 PowerShell输入以下命令验证安装git --version如果输出类似git version 2.47.1.windows.1说明安装成功且 PATH 配置正确。如果提示“git 不是内部或外部命令”那就是 PATH 没生效需要手动检查环境变量。3. 基础环境配置与细节打磨3.1 用户身份配置这一步决定你的提交记录装好 Git 之后先配置用户名和邮箱这一步非常关键。Git 每次 commit 都会记录这两个信息如果没配置提交时 Git 会用系统主机名生成看起来非常奇怪的身份也可能会直接拒绝。打开 Git Bash执行git config --global user.name 你的名字 git config --global user.email 你的邮箱这里的--global表示全局生效针对当前系统用户的所有仓库。如果你想对某个仓库单独设置身份可以去掉--global在该仓库目录下执行git config user.name和git config user.email。这个场景在同时使用公司 Git 和个人 Git 时很常用比如公司仓库用公司邮箱个人开源项目用 Gmail。配置完之后可以查看一下当前所有配置git config --list注意邮箱最好和你的代码托管平台GitHub、GitLab、Gitee注册邮箱保持一致这样提交记录的头像才能正确关联。如果你特别在意邮箱隐私GitHub 支持开启 “Keep my email addresses private”会给你一个类似xxxxxusers.noreply.github.com的匿名邮箱那个也可以拿来配 Git只是在团队内部协作时别人看提交记录找到的就不是你的真实邮箱了。3.2 默认分支名、换行符与代理配置Git 默认分支名是master但近年来主流平台新建仓库时默认分支已经是main。为了保持一致避免本地仓库和远程仓库默认分支不一样导致的上传时分支名冲突建议统一设置git config --global init.defaultBranch main这样你在任何地方执行git init默认分支就是 main。这里多说一句分支名本身没有魔法叫什么都行main只是当前社区约定俗成的选择。换行符的配置在安装时已经处理过但如果你用了其他工具改过也可以通过命令来修正git config --global core.autocrlf true在 Windows 上true表示 checkout 时转成 CRLFcommit 时转回 LFLinux 和 macOS 上通常设成input也就是保留原样仅在提交时转 LF。代理配置是另一个很容易踩坑的点。如果你是公司网络或者本地开了代理工具HTTP 和 HTTPS 代理可以这样配置git config --global http.proxy http://127.0.0.1:7890 git config --global https.proxy http://127.0.0.1:7890假设代理端口是 7890 就填 7890实际端口以你的代理工具为准。配置完成后clone 和 fetch 都会走代理速度会有明显提升。不想要的时候删除配置git config --global --unset http.proxy git config --global --unset https.proxy有些同事的仓库走的是 SSH 协议SSH 的代理是独立配置的后面讲 SSH 时会提到。3.3 解决 Git 终端乱码与 commit message 编辑器问题Windows 上 Git 的乱码问题几乎是必现的尤其是在 Git Bash 里查看中文文件名、中文 commit message、或者执行git log时显示成\354\227\254\352\270...这样的转义序列。这个问题的根源是 Git 在 Windows 上的编码识别默认不是 UTF-8。在 Git Bash 里直接修改全局配置可以解决git config --global core.quotepath false git config --global gui.encoding utf-8 git config --global i18n.commit.encoding utf-8 git config --global i18n.logoutputencoding utf-8core.quotepath false是最重要的一行它让 Git 在显示中文文件路径时直接显示中文而不是用八进制转义序列。另外三个配置保证提交信息读取和输出时统一走 UTF-8。如果你在 Git Bash 里运行git log输出的中文还是乱码可以再试一下在 Bash 里执行export LESSCHARSETutf-8这个环境变量影响的是less分页器的编码。Git 默认用 less 来分页显示 log 输出它按自己的字符集去解码不设对就会乱。commit message 编辑器的问题前面铺垫过了如果不小心选成了 Vim 或者后来想换命令是这样git config --global core.editor code --waitcode --wait是 VS Code 的命令行参数意思是 Git 调用编辑器时打开 VS Code 并等待你关闭文件后再继续执行。在 Windows 上这个配置会按引号里的命令找到 VS Code 的可执行文件。如果没有用 VS Code也可以改成notepad或notepad的路径。这个不复杂但能救回很多对着 Vim 不知道按哪个键的同学。4. SSH 密钥配置与远程仓库免密连接4.1 SSH 协议和 HTTPS 协议的区别和选择远程仓库连接有两种主流方式HTTPS 和 SSH。HTTPS 的方式最直接clone 时直接填仓库地址推送的时候输入用户名密码或者 Personal Access TokenPAT。这种方式的主要问题是每次 push 都要输凭证或者需要依赖 Windows 凭据管理器去记住密码。在 GitHub 上HTTPS 密码早已失效必须使用 PAT而 PAT 像一串很难记的长随机数往密码框里粘贴时还特别容易出错。SSH 的方式则属于公钥加密通信。你生成一对密钥私钥留在本地公钥填到代码托管平台的 SSH Keys 设置里。之后每次 Git 通过 SSH 协议连接远程仓库时服务器用公钥验证你的身份本地私钥自己保管整个过程免密、安全而且没有 HTTPS 那种临时密码过期的问题。对于日常开发来说SSH 是效率最高、最省心的方案。下面就从生成密钥开始把整个流程走一遍。4.2 生成密钥对实操步骤与参数解释打开 Git Bash执行ssh-keygen -t ed25519 -C 你的邮箱或备注这里我用了ed25519而不是更老的 RSA。ed25519 是更现代的椭圆曲线签名算法密钥更短、生成更快、安全性也足够。如果你的 Git 托管平台或者服务器不支持 ed25519极少见老旧的 GitLab 自建实例可能有这个情况可以退一步用ssh-keygen -t rsa -b 4096 -C 你的邮箱或备注-t指定算法类型-b指定位长RSA 的话 4096 位是当前推荐的最低强度。ed25519 不需要-b参数因为它的密钥长度是固定的。执行过程中会询问保存位置默认在~/.ssh/id_ed25519这里建议保持默认。接着会让你设置 passphrase这一步其实是给你的私钥再加一把锁就算有人拿到了你的私钥文件没有 passphrase 也无法使用。如果你嫌每次用 key 都要输密码麻烦可以留空直接回车如果想要更安全但又能省去每次输入的麻烦可以配合 ssh-agent 来做后面会讲。生成完成后用下面的命令查看公钥cat ~/.ssh/id_ed25519.pub公钥是一串ssh-ed25519 一大段字符串 你的邮箱格式的文本把它完整复制下来一会儿要填到平台里。4.3 将公钥配置到 GitHub、GitLab、Gitee以 GitHub 为例登录 GitHub 后依次进入 Settings → SSH and GPG keys → New SSH key。Title 可以填My Windows PC或者任何你能认出来的名字便于以后管理多台设备时区分。Key 那一栏粘贴刚才复制的公钥内容保存即可。Gitee 的操作是头像下拉菜单 → 设置 → 安全设置 → SSH 公钥GitLab 则是在 Preferences → SSH Keys。三个平台本质相同都是把你的公钥文本放进平台的白名单里。配置完之后测试一下连接ssh -T gitgithub.com看到类似Hi username! Youve successfully authenticated, but GitHub does not provide shell access.就说明密钥已经生效。Gitee 的测试地址是ssh -T gitgitee.comGitLab 需要根据你自己的域名走比如ssh -T gitgitlab.example.com。这个测试相当于一次握手验证服务器告诉你“我认出你是谁了但我不给你 shell 环境”正常的不是报错。4.4 ssh-agent 与私钥管理多密钥场景下的最佳实践如果你只有一台电脑、一套密钥上面的配置已经够用了。但一个很现实的场景是个人电脑同时要连 GitHub、公司 GitLab甚至可能还有客户服务器的 SSH。多套密钥的时候如果每个密钥都叫id_ed25519会互相覆盖。更好的习惯是给不同用途的密钥命名比如ssh-keygen -t ed25519 -C work email -f ~/.ssh/id_ed25519_work ssh-keygen -t ed25519 -C personal email -f ~/.ssh/id_ed25519_personal使用的时候通过 SSH 配置文件~/.ssh/config来指定不同主机使用哪个密钥Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_personal Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_work这样当你 clone 或者 push 到不同平台时Git 会自动根据 Host 匹配对应的私钥不需要每次手动指定。ssh-agent 的作用是替你保管已经解锁的私钥这样使用带 passphrase 的密钥也能做到一次输入、会话内免密。常见的启动方式是eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519第一条命令启动 ssh-agent 后台进程并设置好环境变量第二条命令把私钥加入当前会话。之后在这个会话内再用同一密钥就不会再提示输入 passphrase。Windows 上如果你装了 Git for WindowsSSH 相关的工具是自带的不需要额外安装任何东西。如果你用的是原生 OpenSSHWindows 10 1809 之后系统自带可能在服务和密钥权限上有细微差异但只要测试通了就不需要关心底层用的是哪套 SSH 实现。5. 常见问题与排查技巧实录5.1 高频报错速查表我把这些年遇到过的高频问题做成一个表方便你直接对照排查。问题现象常见原因解决办法git不是内部或外部命令安装时 PATH 没选对或环境变量没刷新重新执行安装程序修改 PATH或手动将C:\Program Files\Git\cmd加入系统 PATHclone/push 时反复要求输密码远程地址用的是 HTTPS或 SSH 密钥没配置成功改用 SSH 地址从https://github.com/...换成gitgithub.com:...Permission denied (publickey)公钥没加进平台或本机自动使用了错误的私钥检查ssh -T gitgithub.com输出确认公钥已添加必要时配置~/.ssh/config指定密钥git commit时进入 Vim 无法退出默认编辑器是 Vim新手不知道命令按Esc输入:wq回车保存退出或重新配置core.editor中文文件名变成\345\233\276\347\211\207core.quotepath默认为 true执行git config --global core.quotepath falsefatal: Not a git repository当前目录不在仓库内先执行git init或cd进入仓库目录src refspec main does not match any本地还没有任何提交空仓库推送先git add和git commit之后再 pusherror: failed to push some refs远程仓库有本地没有的提交先git pull --rebase拉取合并再 pushGit 操作极慢、卡在连接网络问题或代理配置不正确重新配置http.proxy与https.proxy或者关掉代理The file will have its original line endings警告换行符转换行为与仓库现状不一致检查core.autocrlf设置与团队约定统一5.2 密钥权限错误这个报错在 Windows 上尤其迷惑如果你在 SSH 连接时看到Permissions for C:\\Users\\xxx/.ssh/id_ed25519 are too open.这是 SSH 在检查私钥文件权限时发现文件权限过于宽松出于安全考虑直接拒绝了。这个报错在 Linux 上很常见因为默认 umask 可能放开了其他用户读权限Windows 上的触发场景不太一样——通常是私钥文件从别处复制过来或者通过某些同步工具同步下来导致文件 ACL 权限继承了不正确的用户组。解决办法是右键私钥文件 → 属性 → 安全 → 高级 → 禁用继承 → 将继承的权限转换为显式权限 → 移除除了当前用户之外的所有条目最后保证当前用户有完全控制权限其他用户全部删除。改完这个再执行一次ssh -T gitgithub.com验证。5.3 清除错误记住的凭据与缓存如果你的电脑以前用 HTTPS 方式连过远程仓库Windows 凭据管理器里会缓存用户名和密码或者 PAT。后来你切换成 SSH 方式却发现 Git 仍然尝试用 HTTPS 凭证可能是因为该仓库的 remote 地址还是 HTTPS 的。先看一下当前仓库的远程地址git remote -v如果是https://github.com/...把它改成 SSHgit remote set-url origin gitgithub.com:username/repo.git如果凭据管理器里存了错误的 PAT 导致推送失败可以在 Windows 的“控制面板 → 用户账户 → 凭据管理器”里找到git:https://github.com条目直接删除下次连接时会重新要求输入或者干脆换 SSH 地址一劳永逸。5.4 远程仓库分支名不匹配时的处理新建远程仓库时如果平台默认分支是 main而你本地按旧习惯用 master推送时会提示分支不存在。常见做法是先把本地分支改名git branch -M main-M强制改名不管当前分支是否叫 master 都能改成 main。改完之后再git push -u origin main这样本地 main 分支就和远程 main 建立了跟踪关系。如果你还没有任何提交远程是空仓库可以直接git init git add . git commit -m first commit git branch -M main git remote add origin gitgithub.com:username/repo.git git push -u origin main这套流程能避免 90% 的新手刚创建仓库时的报错。6. 日常使用中值得养成的几个习惯6.1 提交前检查变更内容很多初学者喜欢git add .一把梭然后直接 commit。这个习惯很危险因为会把临时文件、编译产物、密钥文件不小心提交进去而且一旦提交上去再清理历史会非常痛苦。建议提交前先git status git diff查看被修改的文件列表以及具体的改动内容。如果文件太多可以用git diff --stat先看统计觉得没问题再git status确认全部文件都是想要提交的。这个习惯能帮你提前拦截掉一大堆不该提交的东西。6.2 .gitignore 要在一开始就配好新建仓库时最值得花十分钟做的就是写好.gitignore。不同语言和工具链的通用模板可以从 GitHub 的 gitignore 仓库里找比如Windows、VisualStudioCode、Node、Python这些模板都已经维护得很完善。如果你不确认某个路径该不该忽略遵循一个简单原则能生成出来的文件、包含密钥或密码的文件、个人本地配置文件比如 IDE 的工作区文件都该忽略。有个常见的反例是某同事把项目整个node_modules目录提交到了 Git 仓库结果 clone 下来后发现仓库体积巨大操作卡成幻灯片。这个问题通过事后清理也能解决但让所有参与项目的人心累不如一开始就拦住。就算不慎提交了也不要乱删历史优先是添加到.gitignore再让远程仓库同步忽略。6.3 多用 fetch 而不是直接 pull团队协作时每次开工前先git fetch一下看看远程有没有新的分支和提交。git fetch只下载远程数据不会改动你当前的工作区没有副作用而git pull默认会进行一次 merge如果你的工作区有未提交的修改可能会引发冲突。我自己的习惯是开工前先看一眼git fetch --all --prune git status--prune会清理本地已经删除的远程分支的引用保持远程跟踪列表干净。看到远程有哪些变化后再决定是 merge、rebase 还是直接切分支。这个习惯比直接git pull安全很多尤其是多人协作、分支复杂的项目里能少踩好多坑。6.4 报错信息要完整拍下来或者复制原文排查 Git 问题最忌讳只截个“它报错了”的图却不带完整报错文本。Git 的报错信息很长但很多关键线索就在最后几行。比如fatal: unable to access https://...: OpenSSL SSL_read: Connection was reset, errno 10054这个报错意味着访问远程地址时连接被重置可能是网络代理、防火墙或者中间设备拦截导致的。如果只看前半句“unable to access”就很容易被误导到权限方向白白浪费排查时间。解决问题时把完整的报错文本复制到搜索引擎、或者发给同事得到的答案准确率会高很多。这也是我常年建议新人的一个习惯报错信息全文优先截图其次不要只描述“我 push 失败了”这种没有信息量的话。7. 最后分享两点个人经验如果你照着教程走到了这一步Git 的安装、配置和 SSH 密钥应该已经全部打通。最后分享两个我在实际工作中觉得非常重要的细节。第一私钥一定不要上传到任何网盘、代码仓库、聊天工具里。私钥是你身份的证明拿到私钥等于拿到你代码仓库的访问权限。如果你怀疑私钥泄漏立刻在托管平台删除对应公钥、重新生成一对新的然后删掉本地旧的私钥文件。这个操作成本很低但很多人会拖直到出现安全问题才后悔。第二Git 的配置文件是可迭代的。今天配了core.autocrlf明天可以加init.defaultBranch后天还能加自定义别名。比如给常用命令设置简写git config --global alias.st status git config --global alias.co checkout git config --global alias.br branch git config --global alias.lg log --oneline --graph --all --decorate之后输入git st、git co、git lg会比完整命令快不少。但要注意别名只是你本地的行为不会影响别人看你的提交所以放心大胆地改。Git 的配置文件本质上是跟随你个人的重点是你清楚每一项的含义而不是盲目复制别人的配置。我在实际换过几次电脑之后最大的感受是第一次配置 Git 环境时把这些底层逻辑搞清楚后面每次换设备都只是重复劳动不会有任何障碍。希望这篇教程能帮你把这一步走扎实。
