Git 安装配置全流程：向导选项、中文乱码与 SSH 密钥避坑

Git 这东西几乎每个开发者的机器上都有但真正把它装明白的人不多。我见过太多人装完之后提交代码时邮箱是默认的、换行符把整个文件标红、中文文件名显示成一串八进制数字然后在群里问为什么我的 diff 全是红的。所以这篇 Git 安装教程不打算只告诉你点下一步而是把安装向导里那十几个选项背后的逻辑、装完必须做的配置、以及踩过的坑一次性讲清楚。不管你是刚学编程的新手还是换新电脑重装环境的老手照着走一遍能省掉后面几个月里零零碎碎的返工。整套流程大概半小时其中真正需要你做决策的地方只有四处。1. 装之前先想清楚Git 到底给你解决了什么问题1.1 版本控制的本质是一次思路转变很多人第一次接触 Git 会把它理解成代码备份工具这个理解不算错但少了一半。备份只解决了我改坏了想回到昨天的问题而 Git 解决的是我改坏了想回到昨天同时不想丢掉今天新写的功能而且我还要知道这两部分改动分别是谁在什么时候改的。前者的心法是复制粘贴加日期命名后者的心法是一条可以分叉、可以合并、可以回溯的时间线。这条时间线在物理上就是你项目目录下那个隐藏的.git文件夹。你把 Git 装好、在项目根目录敲一句git init这个文件夹就出现了里面存着所有历史快照、分支指针和配置。理解这一点很重要Git 是分布式的你本地那份仓库就是完整的仓库不是服务器的一个工作副本。断网状态下你照样能提交、能看历史、能建分支等有网了再推上去。这也是它比早期集中式方案更抗折腾的根本原因。对新手来说这个认知带来的第一个实际影响是你不需要在装完 Git 后立刻连上任何远程仓库。本地先建一个空目录练手git init、改文件、git add、git commit这一套能跑通安装环节就算合格了。很多人卡在第一步是因为一上来就想推代码结果被 SSH 密钥和认证拦住误以为是安装出了问题。1.2 装之前要确认的三件事第一件是权限。Windows 上如果你用的是公司配的电脑可能没有管理员权限安装向导跑到最后会报错。这种情况提前找 IT 或者改用免安装的便携版别装到一半才发现。第二件是已有的版本。在终端里敲git --version如果已经有输出先看版本号。低于 2.20 的版本建议升级因为init.defaultBranch这类配置项在老版本里根本不认识你配了也没用会报warning: init.defaultBranch is not a valid configuration。目前主流稳定版本在 2.4x 到 2.5x 之间新装直接用最新版就行。第三件事是想清楚你要装哪几种壳。Git 本体是命令行的但围绕它有一堆图形客户端Windows 上的 TortoiseGit大家习惯叫小乌龟、跨平台的 SourceTree、以及 VS Code、IDEA、PyCharm 这些 IDE 里内置的 Git 集成。我的建议是本体加一个图形客户端就够先把命令行练熟图形工具当辅助。原因后面第 6 章会展开。2. Windows 平台的 Git 安装全流程2.1 安装包从哪来怎么选官方下载地址是git-scm.com首页那个大按钮会根据你的系统自动推荐对应版本。文件名形如Git-2.45.2-64-bit.exe看到64-bit就对了现在基本没有 32 位系统需要照顾。有个现实问题官方源在国内下载偶尔会很慢几十兆的包能跑十几分钟。如果你遇到这种情况可以用国内的一些镜像站点取安装包比如 npmmirror 的二进制镜像目录下就有 git-for-windows 的完整归档。用镜像的时候要注意核对版本号和文件名格式别下到某个来路不明的精简版。还有一个选择是便携版PortableGit-xxx-64-bit.7z.exe解压即用不写注册表。适合装在 U 盘里带走或者在公司电脑上没有管理员权限时应急。代价是右键菜单和 PATH 环境变量需要你自己手动配稍微麻烦一点。2.2 安装向导里那十几个页面逐个拆解这是整篇教程最值得看的部分。Git for Windows 的安装向导页数多每一页都给三四个选项很多人一路 Next然后就出现了后面所有的奇奇怪怪的问题。第一页组件选择Select ComponentsWindows Explorer integration下面有两个子项Git Bash Here和Git GUI Here。这两个强烈建议勾上它决定了你在任意文件夹里右键能不能直接打开 Git 命令行。日常用的频率极高。Associate .git* configuration files with the default text editor建议勾。以后双击.gitignore、.gitattributes会直接用编辑器打开省事。Associate .sh files to be run with Bash看你用不用 shell 脚本写脚本的话勾上。最下面有个Add a Git Bash Profile to Windows Terminal如果你用 Windows Terminal这个勾上体验很好。第二页默认编辑器Default Editor这一页问你git commit时如果不带-m参数用哪个编辑器写提交信息。默认是 Vim对没用过的人是个灾难——进去之后不知道怎么退出。我的做法是有 VS Code 就选 VS Code没有就选 Notepad。选 Vim 也不是不行但你得先知道按i是插入、Esc之后打:wq是保存退出。提示这一页选错了不用重装后面用git config --global core.editor code --wait可以随时改回来。第三页默认分支名Initial branch name新版本会问你是用master还是main。这是个纯粹的习惯问题现在社区主流新建仓库用main老项目里大量还是master。我的建议是选main同时你后面可以在别的老项目里单独改回 master。这里不用太纠结因为它只影响git init时创建的第一个分支叫什么。第四页PATH 环境变量Adjusting your PATH environment这一页是重中之重三个选项分别是选项含义适用场景Use Git from Git Bash only不把 git 命令加进系统 PATH只想用 Git Bash不想污染环境变量Git from the command line and also from 3rd-party software加进 PATH但只加 Git 自己的推荐绝大多数人用这个Use Git and optional Unix tools from the Command Prompt连ls、find、sort这些 Unix 命令一起加进 PATH不推荐会和 Windows 自带命令冲突选第二项。第三项听起来很美实际会出问题Windows 自带的find.exe和 Unix 的find完全不是一回事一旦 PATH 优先级搞乱你在 CMD 里敲find可能报一堆奇怪的参数错误。这个坑我踩过排查了半天才发现是安装时多勾了一个选项。第五页HTTPS 传输后端两个选项Use the OpenSSL library和Use the native Windows Secure Channel library。前者跨平台行为一致后者走 Windows 自己的证书体系公司内网有自签证书的场景更方便。普通用户选默认的 OpenSSL 就行用哪个都不影响你克隆公开仓库。第六页行尾换行符Line ending conversions这一页有三个选项是全篇最容易出问题的地方Checkout Windows-style, commit Unix-style line endings推荐检出时把 LF 转成 CRLF提交时再转回 LF。Checkout as-is, commit Unix-style line endings检出不动提交时转成 LF。Checkout as-is, commit as-is完全不转换。理解这一页要先知道Windows 和 Linux/macOS 对换行的表示不同Windows 用两个字符CRLFUnix 系用一个字符LF。如果不管团队里 Windows 同事改一行代码Git 会认为整个文件每一行都变了diff 一片红。选第一项最稳。但要注意如果你团队里所有人都只在 Linux 上协作或者项目里有.gitattributes文件显式声明了行尾规则那这个全局设置会被覆盖不用担心。第七页终端模拟器Use MinTTY还是Use Windows Console。选 MinTTY它是专门为 Git Bash 做的终端支持更好的窗口缩放、复制粘贴和字体渲染。用 Windows Console 会出现中文显示异常、窗口不能随意拉伸等问题。第八页git pull的默认行为三个选项对应三种策略默认的fast-forward or merge、rebase、only ever fast-forward。新手选默认。等你理解了 rebase 和 merge 的区别想改可以用git config --global pull.rebase true随时切。第九页凭据助手Credential Manager选Git Credential Manager。这个组件会把你第一次输入的用户名密码/令牌存到 Windows 凭据管理器里之后推送就不用反复输入了。不选的话每次 push 都要重新输账号密码非常痛苦。第十页额外选项Enable file system caching勾上能显著加快git status在大仓库里的速度。Enable symbolic links需要管理员权限普通项目用不到不勾也行。真需要的时候可以改回来。2.3 验证安装是否真的成功了装完之后关掉所有已经打开的终端窗口重新开一个这一步很多人忽略。因为 PATH 环境变量的更新只对新开的进程生效你在装之前就开着的 CMD 里敲git --version大概率提示不是内部或外部命令。重新开一个终端依次敲git --version where git git config --list --show-origin第一条应该输出类似git version 2.45.2.windows.1。第二条会列出 git.exe 的实际路径正常应该是C:\Program Files\Git\cmd\git.exe。第三条会把当前所有配置和它们所在的文件列出来如果输出里出现了file:C:/Program Files/Git/etc/gitconfig说明系统级配置文件已经被正确加载。然后在任意文件夹里右键看菜单里有没有Open Git Bash here。有的话安装环节全部通过。3. macOS 与 Linux 的安装方式对比3.1 macOS 的三种装法最省事的一种是敲一句git --version。macOS 自带一个 Git 的壳但那个版本其实是随 Xcode Command Line Tools 附带的第一次敲会弹窗问你要不要安装命令行工具点确认等几分钟就好。这个装法的缺点是版本可能偏旧而且没法方便地升级。第二种是官方安装包从git-scm.com下.dmg双击安装。好处是版本新坏处是以后升级还得手动下载覆盖。第三种是 Homebrew也就是brew install git。这是我最推荐的升级一句brew upgrade git就完事。唯一要注意的是安装完要确认 PATH 里的 git 指向的是 Homebrew 那份用which -a git能看到所有匹配项如果/usr/bin/git排在前面需要在~/.zshrc里把/opt/homebrew/bin往前挪。3.2 Ubuntu 与 CentOS 的包管理器安装Debian/Ubuntu 系sudo apt update sudo apt install -y gitCentOS 7 用 yumCentOS 8 及之后的 Stream 版本用 dnf# CentOS 7 sudo yum install -y git # CentOS 8 / Rocky / AlmaLinux sudo dnf install -y git这里有个坑要提醒Ubuntu 的 apt 源里那份 Git 常年不更新。你在一台 Ubuntu 20.04 上敲git --version很可能得到 2.25 这种四五年前的版本init.defaultBranch它就不认识。解决办法是加官方的 PPAsudo add-apt-repository ppa:git-core/ppa sudo apt update sudo apt install -y git加完 PPA 再装版本就能跟上。CentOS 系如果源里的太旧可以走源码编译或者用第三方仓库具体看你的运维规范。3.3 什么时候才需要源码编译源码编译的场景其实很窄老旧的服务器系统、需要开启某些默认不带的编译选项比如特定的大文件支持、或者内网环境完全不能访问外部软件源。编译流程大致是装依赖、下载源码包、make prefix/usr/local all、sudo make prefix/usr/local install。对绝大多数人来说这一步可以永远跳过用包管理器最省心。4. 装完必须做的全局配置别急着写代码4.1 身份标识这是你所有提交的签名Git 每一次提交都会把作者信息写进历史而且这个信息是不可更改的除非你改写历史。如果你不配Git 会用机器的用户名和主机名拼一个出来推上去之后同事看到的作者是AdministratorDESKTOP-XXXX非常尴尬而且统计贡献度的时候根本认不出是你。git config --global user.name 你的名字或昵称 git config --global user.email 你的邮箱邮箱建议和你代码托管平台Gitee、GitHub 等上注册的邮箱保持一致这样提交记录才能正确归到你账号名下。如果你不希望真实邮箱暴露在公开提交里平台一般提供noreply类型的邮箱地址用那个填进去就可以。配置完用git config --global --list确认一下。全局配置写在用户目录下的.gitconfig文件里Windows 上路径是C:\Users\你的用户名\.gitconfigmacOS 和 Linux 是~/.gitconfig。这个文件是纯文本出问题了直接编辑它比敲命令快。4.2 换个默认分支名顺便解决中文显示git config --global init.defaultBranch main git config --global core.quotepath false第一条刚才说过了新建仓库时默认分支就叫 main。第二条core.quotepath false是个纯收益的设置。Git 默认会把非 ASCII 字符也就是中文转义成\344\275\240\345\245\275这种形式显示在git status里。你改成 false 之后中文文件名就正常显示了看git status时能一眼认出改了哪个文件。这个设置不影响文件本身内容只管显示。4.3 行尾、编码和大小写这几个隐蔽配置# Windows 用户 git config --global core.autocrlf true # macOS / Linux 用户 git config --global core.autocrlf input # 推荐避免大小写重命名导致的问题 git config --global core.ignorecase falsecore.ignorecase这一条要解释一下。Windows 和 macOS 的文件系统默认不区分大小写所以 Git 会跟着把core.ignorecase设成 true。后果是你本地有个Readme.md想把它改名成README.mdgit status里什么都不显示因为在这两套系统看来这是同一个文件。等你推到 Linux 服务器上那里区分大小写就会突然多出一个文件或者出现路径冲突。设成 false 之后这种重命名能正常被追踪到。还有一个容易被忽略的是core.longpaths。Windows 传统上限制路径总长 260 个字符深目录的 Node.js 项目很容易超。加上这句git config --global core.longpaths true4.4 凭据存储别再每次输密码Windows 上装 Git Credential Manager 之后默认就是可用的。macOS 上git config --global credential.helper osxkeychainLinux 上如果装了 libsecretgit config --global credential.helper libsecret如果不方便装这些用store也可以但它是明文保存到~/.git-credentials里的只适合个人机器公用服务器千万别用。5. SSH 密钥配置与代码托管平台对接5.1 生成密钥对比起每次用账号密码SSH 密钥是更省事也更稳妥的方式。生成命令ssh-keygen -t ed25519 -C 你的邮箱-t ed25519指定算法它比 RSA 更短更快现在的平台基本都支持。如果你的目标平台比较老或者公司内网的 Git 服务版本很旧那就退回 RSAssh-keygen -t rsa -b 4096 -C 你的邮箱回车之后会问你保存路径默认~/.ssh/id_ed25519就好然后问你要不要设密码短语个人电脑上直接回车留空省得每次都要输。生成完在~/.ssh/目录下会多出两个文件没有.pub后缀的是私钥这个东西绝对不能发给任何人、不能提交到仓库有.pub后缀的是公钥可以随便公开。5.2 公钥怎么配到平台上用一条命令把公钥内容复制到剪贴板# macOS pbcopy ~/.ssh/id_ed25519.pub # Windows Git Bash cat ~/.ssh/id_ed25519.pub | clip # Linux装了 xclip xclip -sel clip ~/.ssh/id_ed25519.pub然后打开你的代码托管平台在个人设置里找 SSH 密钥那一栏粘贴进去标题随便起一个能认出是哪台机器的名字。Gitee 和 GitHub 的路径大同小异都在账号设置的安全设置或SSH and GPG keys里。配完验证一下ssh -T gitgithub.com ssh -T gitgitee.com第一次连接会问你Are you sure you want to continue connecting?输入 yes。看到Hi 用户名! Youve successfully authenticated就说明通了。如果卡在这里很久然后超时多半不是密钥的问题而是网络层的问题换个时间段再试。5.3 多个平台多把密钥怎么管工作一台机器上要同时连公司代码库和个人的 Gitee密钥不能混用。做法是生成不同的密钥文件然后写配置文件ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_work -C workcompany.com ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_personal -C meexample.com在~/.ssh/config里写Host company-git HostName git.company.com User git IdentityFile ~/.ssh/id_ed25519_work Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_personal这样公司仓库的远程地址要用company-git:组名/项目.git这种别名形式ssh -T company-git能单独测试。注意 Git Bash 和部分 Windows 环境对~/.ssh/config的文件权限比较敏感如果报UNPROTECTED PRIVATE KEY FILE之类的错把私钥文件权限收紧即可。6. 图形客户端怎么选怎么和命令行配合6.1 TortoiseGit 小乌龟的安装要点TortoiseGit 是 Windows 上用得最多的右键菜单式客户端因为它把操作直接挂在文件资源管理器的右键里直觉性强。安装时有两个注意点一是先装 Git 本体再装小乌龟因为小乌龟需要找到 git.exe 的位置顺序反了它会提示找不到。二是安装过程中会问你 SSH 客户端选哪个如果用我们前面配好的密钥选OpenSSH, Git default SSH Client指向 Git 自带的那份不要选 TortoiseGitPlink除非你打算额外维护一套 PuTTY 格式的密钥。小乌龟还有个语言包装完可以切成中文界面。它的提交对话框里能直接看到每个文件的具体改动比命令行直观适合做提交前的最后确认。6.2 SourceTree 与 IDE 内置的 Git 集成SourceTree 的优点是跨平台、可视化历史图谱做得漂亮看分支合并关系一目了然。缺点是首次启动要登录账号而且大仓库加载慢。VS Code 和 IDEA/PyCharm 这一系的编辑器内置了 Git 集成日常的 add、commit、push、切分支都能在界面里点。这里有个细节值得说你在 PyCharm 里点一次刷新它后台实际执行的是类似这样一条命令git -c diff.mnemonicprefixfalse -c core.quotepathfalse --no-optional-locks status --porcelain -z这串参数的意思分别是临时把 diff 的前缀设成 a/b 之外的形式以适配自己的展示逻辑把中文路径正常显示而不是转义不使用可选锁避免和 IDE 自己的文件监听抢锁输出机器可读的格式。你在 IDE 里看到中文路径乱码或者状态刷新不出来多半就是这几个参数在作怪。知道这一点排查时你就能自己手动敲一遍同样的命令看输出到底是哪一步不对。6.3 命令行和 GUI 的分工建议我的习惯是日常提交、看状态、切分支用命令行看历史图谱、处理复杂冲突、做交互式 rebase 用 GUI。原因很实在——命令行的输出是文本出了问题能复制粘贴出来搜索GUI 的报错经常是一句模糊的对话框你不知道背后执行了什么。另外任何 GUI 操作最终都等价于某条 Git 命令反过来不成立。所以命令行会了GUI 只是效率工具只会 GUI遇到图形界面覆盖不到的场景就抓瞎。7. 安装后最容易踩的坑与排查手册7.1 命令找不到、版本错乱症状是在终端敲git提示不是内部或外部命令但你明明刚装完。三个检查方向第一终端是不是安装之前就开着的关掉重开。第二PATH 里到底有几份 gitWindows 上用where gitmacOS/Linux 上用which -a git如果出现了多份把不需要的在 PATH 里挪后或者卸载掉。第三虚拟机或者 WSL 里另有一套环境你在宿主机的终端里配的东西进 WSL 之后完全不生效需要在 WSL 里重新配一遍。7.2 中文乱码的三种表现现象原因解决git status里中文名显示成八进制core.quotepath默认开启git config --global core.quotepath false提交信息里的中文变成乱码终端字符集不是 UTF-8Windows 终端切到 UTF-8 编码或在 Git Bash 里设置LANGzh_CN.UTF-8diff 里中文内容显示异常文件本身编码不是 UTF-8用编辑器统一转成 UTF-8 无 BOM第三种情况尤其常见于老项目Windows 记事本保存出来的UTF-8其实带 BOMGit 会把它当成文件内容的一部分导致第一行永远显示被修改。7.3 提交和推送阶段的典型报错fatal: not a git repository你不在仓库目录里。往上找找有没有.git文件夹或者在子目录里执行的话确认它在仓库范围内。Permission denied (publickey)SSH 密钥没配好或者配到了另一个账号上。用ssh -vT gitgithub.com加详细日志看它到底用了哪把密钥。Host key verification failed目标主机的指纹不在known_hosts里或者变了。删掉~/.ssh/known_hosts里对应的那一行重新连一次。OpenSSL SSL_read: Connection was reset网络层面中断了常见于大仓库克隆。可以试试git clone --depth 1只拉最新一次提交或者调大缓冲区git config --global http.postBuffer 524288000。LF will be replaced by CRLF不是错误是提醒。说明你的core.autocrlf正在做转换正常现象。如果团队约定统一用 LF把它改成input或者干脆关掉。7.4 常见问题速查表问题快速定位命令常见原因提交作者不是我git log -1 --format%an %ae全局配置没设或被项目级配置覆盖密码每次都问git config --get credential.helper凭据助手没启用改了大小写没被识别git config --get core.ignorecase值为 true状态刷新很慢git status手敲计时仓库太大或杀毒软件扫描.git目录拉取后本地改动不见了git reflogpull 时用了 rebase 或强制覆盖可以从 reflog 找回路径太长报错git config --get core.longpathsWindows 路径长度限制git reflog这一条要特别记住它是 Git 的后悔药。任何 HEAD 的移动都会被记录包括你以为彻底丢掉的提交。误操作之后先别急着重新 clone先看 reflog。7.5 关于git commit --amend的边界热词里有人搜这个命令顺带说一下。--amend是用来修改最近一次提交的# 只改提交信息 git commit --amend -m 修正后的提交信息 # 把刚 add 的内容补进上一次提交不改信息 git add 遗漏的文件 git commit --amend --no-edit关键限制是如果那次提交已经推送到远程并且别人可能已经拉走了amend 会让本地和远程的历史分叉之后推送需要强制覆盖会把别人的工作搞乱。只对还没推送的提交用 amend这条规则简单记push 之前随便改push 之后改就要小心。8. 装完之后顺手配的几样东西能省很多事8.1 别名把常敲的命令缩短git config --global alias.st status git config --global alias.co checkout git config --global alias.br branch git config --global alias.ci commit git config --global alias.last log -1 HEAD git config --global alias.lg log --oneline --graph --decorate --allalias.lg这条特别值得配。它把提交历史画成一棵树分支的合并和分叉关系一目了然。原始的git log输出很长翻起来累git lg一屏能看几十条排查这个提交是从哪个分支合进来的很有用。8.2 全局忽略文件把 IDE 垃圾挡在仓库外每个项目都有自己的.gitignore但有些东西是跨项目都要忽略的比如系统的.DS_Store、编辑器的.idea/、.vscode/还有各种临时文件。做一份全局忽略git config --global core.excludesfile ~/.gitignore_global然后往~/.gitignore_global里写.DS_Store Thumbs.db *.swp .idea/ .vscode/ *.log要注意全局忽略只对还没被跟踪的文件生效。如果一个文件已经被git add过再往忽略文件里加也没用得先git rm --cached 文件名把它从索引里拿掉。8.3 克隆与首次推送的完整演练装完之后做一次完整演练确保每一环都通# 克隆一个公开仓库验证读权限 git clone https://gitee.com/某个公开项目.git cd 某个公开项目 git lg # 本地新建仓库验证写流程 mkdir demo cd demo git init echo # demo README.md git add README.md git commit -m init: 初始化仓库 git remote add origin gitgitee.com:你的用户名/demo.git git push -u origin main-u参数的作用是把本地 main 分支和远程 origin/main 建立跟踪关系之后在这个分支上直接敲git push和git pull就行不用再带参数。第一次推送如果是 SSH 地址会走前面配好的密钥如果是 HTTPS 地址会弹窗让你输账号和访问令牌。注意现在各大平台基本都不再支持账号密码直接推送HTTPS 方式需要生成访问令牌Token代替密码。令牌的权限可以精细控制只给仓库读写就够别一上来就给全账号权限。9. 我踩过之后总结的几条经验装 Git 这件事本身不难难的是那些默认值不符合你实际场景的地方。我自己换过四五台开发机每次重装都会把这份配置走一遍有几点体会比较深。一是别在安装向导里偷懒。那个行尾转换的选项选了默认值和选了第三个团队协作时的体验差距是巨大的。我见过一个项目因为有人安装时选了as-is导致每次他提交所有文件的每一行都显示被修改review 的时候完全没法看。这种问题事后修复要重写整个仓库的历史代价极高。二是配置要写在全局动作要落在项目。user.name、core.quotepath、core.autocrlf这些适合全局而分支保护规则、提交信息格式这类约束应该写进项目的.gitattributes和提交钩子里让每个克隆仓库的人都自动遵守。只靠口头约定早晚会有人漏掉。三是SSH 密钥别只用一把。个人机器上多生成几把按用途分开写进~/.ssh/config。万一某一把泄露了或者某台设备丢了你只需要在平台上删掉对应的公钥其他环境不受影响。全都用同一把的话出事就得全部重置。四是新环境装完之后先跑一遍完整的克隆、提交、推送流程再开始干活。别等到加班到半夜要紧急修 bug 的时候才发现推送权限没配好。这个验证花不了五分钟能避免的麻烦却不少。我习惯在新机器上克隆一个自己的私有小仓库做测试跑通了再迁主力项目。