先交代一下背景。我见过太多人在 Windows 上折腾 Git下载慢、装完发现 git 命令用不了、好不容易跑起来 push 又弹密码框、想换 SSH 又报 Permission denied……每一个问题单独看都不难但串在一起就能劝退一个刚入门的新手。这篇教程就是冲着这些问题去的。我会从 Windows 平台的实际操作出发把 Git 的下载、安装、环境变量配置、SSH 密钥生成与配置完整走一遍每一步都讲清楚“为什么这么做”而不是只给你一串命令。无论你是刚接触版本控制的学生还是从 SVN 转过来的老开发或者只想把代码安全托管到 GitHub/Gitee 的工程师这篇内容都能直接照着做。1. 先把 Git 在 Windows 上的运行逻辑搞清楚1.1 Git 不是“一个软件”而是一套命令行工具集很多人第一次接触 Git 时会下意识地把它和“安装包”画等号觉得装完就能看到一个界面。实际上 Git 的核心是一个命令行工具集它负责管理你项目目录下的所有文件变更记录。你在 Windows 上安装的 Git for Windows本质上是把 Git 原本在 Linux/macOS 上那套版本控制逻辑完整移植到了 Windows 环境里同时附带了一个模拟 Linux 命令行的终端——Git Bash以及一套图形化的右键菜单。了解这一点很重要因为后续所有“环境配置”本质上都是在告诉 Windows 操作系统Git 装在哪里、命令行如何调用它、它生成的密钥文件放哪里。很多人配不好 Git问题往往出在这个底层逻辑没理顺。在 Git 的语境里有三个最重要的概念工作区你写代码的目录、暂存区准备提交的文件列表、版本库Git 保存历史记录的地方。你在 Windows 资源管理器里看到的是工作区git add把文件送进暂存区git commit才真正把改动写进版本库。理解了这三个区域后面执行命令时就不会一头雾水。1.2 Windows 下 Git 的三种打开方式该用哪个Git for Windows 安装完成后你会获得多种使用入口Git Bash这是最推荐的模式。它模拟了 Linux 终端环境支持ls、pwd、touch这些 Unix 命令路径风格也是/c/Users/xxx这种网上绝大多数教程和命令都是基于这种环境写的照着抄不会出错。CMD命令提示符Windows 自带的终端。Git 安装时如果勾选了把 Git 加入 PATH那么在 CMD 里也能直接敲git --version。但 CMD 不支持ls等 Unix 命令只能使用dir体验比较割裂。PowerShellWindows 新一代终端功能更强但对 Git 命令的兼容性和 Git Bash 仍有细微差别例如别名、管道处理方式不同。从我实操经验看新手的正确选择是 Git Bash。不是因为其他方式不能用而是因为 Git Bash 屏蔽了 Windows 与 Linux 的差异教学、查错、复制命令都最省心。后文的命令我都默认在 Git Bash 里执行。1.3 环境变量的本质让系统能找到 git.exe环境变量是 Windows 系统里的一组全局参数其中Path变量决定了系统在哪个目录搜索可执行文件。你之所以能在任意目录下敲git命令就弹出响应是因为 Git 安装程序把C:\Program Files\Git\cmd这个路径写进了系统Path变量里。如果安装时没勾选对应选项或者装的是绿色版、便携版就会出现“不是内部或外部命令”的报错。这就是环境变量没配好的典型表现。所以与其背一堆配置教程不如先理解环境变量配置 告诉系统 git.exe 放在哪个目录让它在任何路径下都能被找到。明白这条后面遇到问题时你就有排查方向了。2. Git 下载与安装逐项选项详解2.1 下载渠道与版本选择别一上来就点“最新版”Git 官网git-scm.com是首选下载渠道页面会自动识别你的操作系统点击下载即可。但因为服务器在海外国内用户下载速度经常只有几十 KB/s甚至会直接失败。我自己的做法是优先用国内镜像源比如淘宝 npm 镜像npm.taobao.org/mirrors/git-for-windows/或者清华 tuna 镜像mirrors.tuna.tsinghua.edu.cn/git-for-windows/。镜像里的文件与官方完全一致只是分发路径不同下载速度能快几个数量级。版本选择上我的建议是不追最新选择“最新稳定版的前一两个小版本”。因为 Git 的发布节奏较快刚发布的次版本偶尔会有兼容性问题而稍早一点的稳定版经过了社区大量验证Windows 平台上的各种疑难杂症基本都被处理干净了。下载时注意区分 32 位32-bit和 64 位64-bit安装包现在绝大多数电脑都是 64 位但如果你用的还是老旧机器选错架构会导致安装失败或运行异常。2.2 安装向导里每一项到底该怎么选Git 的安装向导选项很多很多人全点“Next”就完事了结果后面用起来处处别扭。这里我把关键几项拆开讲。Select Components选择组件默认勾选的项里注意 “Git Bash Here” 和 “Git GUI Here” 建议保留这会给右键菜单增加两个实用入口方便之后在任意目录快速打开终端。“Additional icons” 里的“On the Desktop”建议取消桌面图标没有实际用处纯属遮挡桌面。“Default text editor”默认编辑器建议保持默认的 Vim或者选择你熟悉的编辑器。如果你不太会用 Vim后面第一次 commit 时发现进入了一个无法退出的界面会非常抓狂。Adjusting your PATH environment调整 PATH 环境变量这一步是重中之重三个选项的含义分别为只从 Git Bash 使用 Git不写入系统 PATHCMD 和 PowerShell 里无法调用 git 命令。从命令行以及第三方软件使用 Git推荐将 Git 加入系统 PATH这是绝大多数人需要的选项。仅从命令提示符使用 Git不纳入 PATH不推荐会让 Git Bash 的 Unix 工具不可用。选择第二项也就是推荐项。这样你在任意终端里都能直接使用 git这也是后面环境配置的基础。Choosing HTTPS transport backendHTTPS 传输后端保留默认的 “Use the OpenSSL library”因为绝大多数平台GitHub、Gitee、GitLab都基于 OpenSSL 证书体系改选项只会在极少数企业内网场景才用得上。Line ending conversions换行符转换这个选项对 Windows 用户影响深远。默认的 “Checkout Windows-style, commit Unix-style line endings” 意思是从仓库检出文件时把换行符转成 Windows 的 CRLF提交时再转回 Unix 的 LF。这个默认行为在团队协作中能避免大量“明明没改代码却显示整文件变动”的问题。如果你单人开发且项目统一使用 LF可以选择第三项但新手请务必保留默认第一项等你理解换行符机制后再按项目需求调整。Configuring the terminal emulator终端模拟器默认的 “Use MinTTY” 是最佳选择。MinTTY 支持更多终端特性比如鼠标操作、更丰富的色彩显示虽然在复制粘贴时需要按 Shift 键但整体体验远胜于使用 Windows 自带终端。建议保留默认。Default branch name默认分支名新版 Git 安装器会询问初始分支名用什么。默认的master或main都可以我建议选择main这更贴近当前 GitHub 新建仓库的默认分支名少一次改名的麻烦。其他选项如 “Enable file system caching”启用文件系统缓存、“Enable Git Credential Manager”启用凭据管理器都保留默认即可前者提升性能后者方便后续 HTTPS 登录。2.3 安装完先做两个验证安装完成后打开 Git Bash依次执行git --version which gitgit --version返回版本号说明安装成功which git返回类似/mingw64/bin/git的路径说明环境变量生效。如果git命令提示找不到说明安装时 PATH 选项选错了回到 2.2 节重装一次或者在后面第 3 节手动配置环境变量。这里插一句我自己的经验装完 Git 后不要立刻打开 VS Code 或其他编辑器。因为编辑器可能缓存了旧的环境变量导致新的 git 命令不可用。建议装完后关掉所有终端和编辑器重新打开再执行验证命令。3. 环境变量配置与 Git 初始化设置3.1 怎么确认环境变量有没有自动配好安装时如果选择了“从命令行以及第三方软件使用 Git”环境变量一般是自动配好的。但有些情况会失效比如使用了绿色版 Git、系统环境变量被第三方软件清理过、安装时选了第一项。我现在带你手动检查一遍这也是环境配置中最容易出错的地方。右键“此电脑” - 属性 - 高级系统设置 - 环境变量在“系统变量”列表中找到Path双击打开检查是否有类似以下路径C:\Program Files\Git\cmdC:\Program Files\Git\mingw64\binC:\Program Files\Git\usr\bin这三个目录分别对应 Git 主命令、MinGW 环境、Unix 工具集。最核心的是cmd目录因为git.exe在那里后面两个通常由安装程序自动添加一般不需要手动干预。另一种检查方式是在 CMD 里执行echo %PATH%在输出中搜索 Git 相关路径。如果在系统变量中没找到就说明需要手动配置了。3.2 手动配置环境变量的具体操作手动配置的场景也不少见特别是那些用了便携版 Git 的朋友。具体操作如下先找到你的 Git 安装目录。比如便携版解压到了D:\Apps\Git那么git.exe通常位于D:\Apps\Git\cmd\git.exe。复制这个cmd目录的完整路径。在“环境变量”窗口的“系统变量”区域找到Path点击“编辑”再点击“新建”粘贴刚才复制的路径。一路点击“确定”保存然后重新打开 Git Bash执行git --version验证。注意修改系统环境变量后必须关闭所有已打开的终端窗口再重新打开否则变更不会生效。这是很多新手配置完还是提示“git 不是内部或外部命令”的最常见原因。还有一个小坑Gitee 或 GitHub 上的某些教程会建议你直接改“用户变量”里的 Path。如果这台电脑只有你一个用户改用户变量和系统变量效果差别不大但如果电脑有多个账号或者你常用 VS Code、Jenkins 等以服务方式运行的工具建议配置到“系统变量”保证所有进程都能读到。3.3 初始化设置用户名和邮箱必须配环境变量解决的是“系统能找到 git”但 Git 还需要知道“你是谁”。这个身份信息会写进每次提交commit记录里是代码溯源的基础。打开 Git Bash执行git config --global user.name 你的名字 git config --global user.email 你的邮箱注意邮箱最好和 GitHub/Gitee 注册邮箱一致这样提交记录才能正确关联到你的账号。--global参数的意思是“当前用户的所有仓库都生效”对应的配置文件位置在C:\Users\你的用户名\.gitconfig。我建议你配完后执行一句验证git config --global --list能看到 user.name 和 user.email 就算配好了。之前遇到过一个同事配置时把邮箱名打错了一个字母结果所有提交记录都串不到他账号上最后只能靠git filter-branch大费周章地改历史非常痛苦。所以这一步务必仔细。3.4 Git 配置的三个层级System、Global、Local理解配置层级对你排查问题很有帮助。Git 的配置共有三层System系统级配置文件在 Git 安装目录下的etc/gitconfig影响这台机器上所有用户。Global用户级配置文件在用户目录.gitconfig影响当前用户的所有仓库。Local仓库级配置文件在仓库目录.git/config只影响当前仓库。三层配置的优先级是 Local Global System即仓库级配置会覆盖用户级配置用户级又会覆盖系统级。当你发现某个仓库的用户名和全局不一致或者某个命令行为很奇怪时优先检查是不是 Local 层级的配置在“捣乱”。比如有些项目要求提交者用公司邮箱你可以在仓库目录下单独执行git config user.name 公司名字 git config user.email 公司邮箱这样只改当前仓库不影响其他项目。4. SSH 密钥生成、配置到平台、连接测试4.1 为什么推荐 SSH 而不是 HTTPS 连接远程仓库往 GitHub 或 Gitee 推送代码主流有 HTTPS 和 SSH 两种协议。HTTPS 的优点是配置简单第一次 push 时输入账号密码或 Token即可缺点是每次 push 都要验证身份虽然凭据管理器能记住密码但遇到公司电脑加密策略、多账号切换时HTTPS 就会变得非常繁琐。SSH 的优势在于一旦生成密钥并配置到平台后续所有 push/pull 都不再需要输入密码完全基于非对称加密自动完成身份认证。而且 SSH 默认走 22 端口部分平台支持 443 端口的 SSH在某些网络环境下比 HTTPS 更稳定。配置 SSH 密钥是 Git 环境配置中绕不开的一环也是“全套教程”的最核心部分。4.2 生成密钥算法选择与实操命令在 Git Bash 里执行ssh-keygen -t ed25519 -C 你的邮箱这里我推荐使用ed25519算法而不是传统的rsa。因为 ed25519 密钥更短、生成更快、安全性更高GitHub 和 Gitee 都早已支持。如果你用的是非常老旧的 Git 版本或企业内部 GitLab 不支持再退回rsassh-keygen -t rsa -b 4096 -C 你的邮箱执行命令后会提示Enter file in which to save the key默认路径是~/.ssh/id_ed25519直接回车即可。Enter passphrase这里可以设置密钥的访问密码。留空或设置都可以。如果设置了每次使用密钥时都要输一次密码好处是即使密钥文件泄露别人也没法直接用。我建议本地个人电脑留空公司电脑设置一个密码安全性和便利性之间做个平衡。生成完成后会在用户目录的.ssh文件夹下生成两个文件id_ed25519私钥自己留着不要给任何人和id_ed25519.pub公钥需要上传到平台。查看公钥内容的命令cat ~/.ssh/id_ed25519.pub输出的一长串ssh-ed25519 AAAAB3... 邮箱就是你的公钥。复制时要复制完整的一整行不要漏掉开头的ssh-ed25519也不要自己添加任何字符。4.3 把公钥配置到 GitHub 和 Gitee以 GitHub 为例登录后点击右上角头像 - Settings - 左侧菜单选择 SSH and GPG keys - 点击 New SSH key。Title 随便填比如“Windows-PC”Key 区域粘贴刚复制的公钥内容最后点击 Add SSH key 即可。Gitee 的路径类似头像 - 设置 - 安全设置 - SSH 公钥。粘贴公钥后保存。这里有一个常见问题同一台电脑上的同一对密钥可以同时配置到多个平台。GitHub、Gitee、GitLab 都能用同一个公钥不需要为每个平台单独生成密钥。因为 SSH 认证过程中平台只需要验证“持有私钥的这个人是否与公钥匹配”与具体平台无关。但也有例外如果你需要区分不同的身份比如 GitHub 用个人邮箱、公司 GitLab 用公司邮箱可以创建多对密钥在~/.ssh/config文件中做 Host 映射这个玩法后面再单独写一篇。4.4 测试 SSH 连接及典型报错处理配置完成后执行ssh -T gitgithub.comGitHub 会返回一段提示首次连接时会询问是否确认 host 指纹输入yes回车即可。成功时你会看到类似Hi username! Youve successfully authenticated, but GitHub does not provide shell access.Gitee 的测试命令是ssh -T gitgitee.com成功时返回Hi 用户名! Youve successfully authenticated, but GITEE.COM does not provide shell access.看到successfully authenticated就说明 SSH 密钥配置成功了。如果提示Permission denied (publickey)先别慌按以下顺序排查确认你测试的仓库地址是 SSH 格式gitgithub.com:用户名/仓库名.git而不是 HTTPS 格式。很多人在这里用错了克隆地址。确认你当前用户目录下的.ssh目录权限正常。Windows 下一般没问题但如果你曾用管理员身份操作过可能导致目录属主异常。可以尝试把.ssh目录删掉重新生成一遍密钥。确认 ssh-agent 正在运行且密钥已加入。执行eval $(ssh-agent -s)然后ssh-add ~/.ssh/id_ed25519再重新测试。还有一个特别隐蔽的坑如果你的用户目录路径含中文或空格偶尔会导致某些老工具读取不到.ssh目录。遇到这种情况可以临时把 HOME 环境变量指向一个纯英文路径或者改用 Windows 自带 OpenSSH 客户端但功能会打折扣。5. 从安装到日常使用的高频问题排查实录5.1 换行符警告CRLF 和 LF 的恩怨第一次在 Windows 上执行git add或git commit时你很可能看到这样的警告warning: LF will be replaced by CRLF in xxx.js这是 Git 在履行换行符自动转换策略。Windows 系统的换行符历史遗留是CRLF回车换行而 Linux/macOS 以及 Git 内部使用的是LF仅换行。Git 在检出文件时把 LF 转为 CRLF让 Windows 编辑器能正常显示提交时再把 CRLF 转回 LF保证仓库里存的文件统一为 LF避免跨平台时出现整文件变动。如果你的团队全是 Windows 用户且项目不涉及跨平台部署可以在仓库根目录添加.gitattributes文件把关键文件类型强制指定为 LF 或 CRLF。比如* textauto *.js text eollf *.bat text eolcrlf.gitattributes是 Git 仓库中非常实用的配置文件它能从根本上统一所有协作者的换行符行为。如果项目里还没有这个文件我建议尽早加上它能让“换行符问题”彻底闭嘴。5.2 每次 push 都弹账号密码框怎么关掉如果你用的是 HTTPS 地址克隆的仓库第一次 push 时 Git 会弹出 GitHub 或 Gitee 的登录窗口。新版 Git for Windows 默认集成了 Git Credential Manager理论上输入一次账号密码后凭据会保存在 Windows 凭据管理器里后续不会再弹。但很多人遇到的问题恰恰是“每次 push 都弹”。原因通常是使用了 Gitee 的账号密码Gitee 已不再支持密码推送必须用私人令牌或者凭据管理器没有正确介入。解决方案很直接——改用 SSH 协议也就是本文第 4 节的内容。把远程地址改成 SSH 格式即可git remote set-url origin gitgithub.com:用户名/仓库名.git改完后再 push 一次后续就不需要再和密码框打交道了。这也是我为什么一直强调“SSH 才是 Git 远程操作的最终归宿”——一劳永逸。5.3 Permission denied 提示八成是密钥没对上在使用 SSH 协议时最典型的报错是gitgithub.com: Permission denied (publickey). fatal: Could not read from remote repository.出现这个提示优先级最高的排查手段是执行ssh -T gitgithub.com确认能否通过验证。如果这里就失败说明密钥没配好。确认公钥已复制完整。粘贴时漏字符、多空格是高频失误。确认你用的是私钥对应的公钥。有人会同时生成好几对密钥然后分不清哪对配到平台上了。最简单的办法是重新生成一对新密钥彻底替换。极少见的情况是 SSH agent 没有正确加载私钥。执行ssh-add -l查看当前加载的密钥列表如果为空执行ssh-add ~/.ssh/id_ed25519。我遇到过一次非常特殊的案例某个项目的远程仓库地址被前任开发配置成了gitgitlab.com:前缀但公司实际用的是自建 GitLab 域名。SSH 客户端根据域名找不到对应配置一直报 Permission denied。这种问题靠看报错信息是发现不了的需要检查git remote -v的地址是否正确。5.4 连接超时连不上 GitHub怎么排查还有一种高频问题不是密钥错误而是纯网络层面执行ssh -T gitgithub.com后长时间卡住最后报Connection timed out。遇到这种情况先判断是不是所有外网都不稳定还是只有 Git 连不上。如果只有 Git 连不上常见的处理思路有两个一是换端口GitHub 的 SSH 服务支持 443 端口可以修改~/.ssh/configHost github.com Hostname ssh.github.com Port 443 User git这样 SSH 连接会走 443 端口绕过部分网络环境对 22 端口的屏蔽。二是检查系统代理设置如果你本机运行了代理工具但 Git 没读到代理环境变量就会造成连接超时。可以在 Git Bash 里临时配置export https_proxyhttp://127.0.0.1:端口号 export http_proxyhttp://127.0.0.1:端口号配置完后再测试 SSH 连接即可。注意这里的代理工具仅用于正常网络访问不涉及任何其他用途。注意本节内容仅为解决正常的网络连通性排查请确保你的所有网络行为符合当地法律法规和平台使用规范。5.5 高频问题速查表现象常见原因推荐排查方法git不是内部或外部命令PATH 未配置手动添加 Git 的 cmd 目录到系统 Path提交时提示配置 user.name/email未设置全局身份执行git config --global配置Permission denied (publickey)公钥未上传或私钥未加载检查公钥完整性和ssh-add -l连接超时网络环境限制 22 端口修改 SSH 走 443 端口或配置代理每次 push 弹密码使用 HTTPS 地址切换远程地址为 SSH 格式LF/CRLF 警告换行符自动转换使用.gitattributes固化规则提交历史显示错误邮箱绑定多个邮箱用git log --format排查并修正 config6. 我踩过的几个坑希望你直接绕开写到最后分享几个我自己在 Windows 上配置 Git 时踩过、也帮别人排查过的坑这些细节通常不会出现在官方文档里但对实际体验影响很大。第一不要把 Git 安装在带空格的深层路径下。默认的C:\Program Files\Git是没问题的但如果你手动改到C:\My Tools\Git 2026\版本2.4x这种目录后续某些第三方工具可能因为路径含空格而解析失败。如果你确实要自定义安装路径尽量选择无空格、纯英文路径。第二升级 Git 前先备份全局配置。Git 升级一般不会动你的.gitconfig但偶尔会因为版本差异导致配置项失效。我的习惯是升级前先复制一份~/.gitconfig到桌面升级后再用git config --global --list快速核对一遍。这个小动作花不了 10 秒却能避免很多莫名其妙的“配置丢了”问题。第三配置多个平台账号时先用ssh -T验证再克隆仓库。很多人喜欢先git clone再测试连接如果密钥有问题clone 报错信息不够直观容易被误导到“权限”“网络”方向。反过来先做一次 SSH 验证能第一时间定位是不是密钥问题。第四VS Code 的 Git 集成依赖的是系统 PATH 里的 git。如果你在 VS Code 的源码管理面板里看不到任何仓库或提示 Git 未安装大概率是 VS Code 启动时没读到 Git 的 PATH。解决办法是先确认终端里git --version正常然后完全退出 VS Code包括托盘图标重新打开。第五也是我最想强调的一点别急着去记命令先理解 Git 的数据流。很多新手卡住不是因为命令不熟而是不知道pull和fetch有什么区别、merge和rebase各自解决什么问题。等你能在脑子里建立“工作区、暂存区、本地仓库、远程仓库”这条数据链路之后所有命令都只是这条链路上的操作按钮不需要背。Git 这套工具学会基本操作可能只需要一小时但真正用得顺手需要在实际项目中反复打磨。这篇教程把 Windows 上从零到一的完整链路都过了一遍你现在应该能独立完成 Git 的下载安装、环境变量配置、SSH 密钥配置以及常见问题排查。剩下的事情——比如分支策略、冲突解决、历史改写——就是在日常提交中慢慢积累了。如果配置过程中还有哪一步不顺畅回头看对应章节大概率能找到答案。