★ FEATURED ARTICLE 想在一台刚装好 Ubuntu 的机器上把 Git 跑起来是每个开发者都绕不开的第一步。这个操作看起来简单但实际折腾过的人都知道它牵扯到软件源更新、版本选择、身份配置、SSH 密钥、换行符处理、中文乱码修正等等一堆细节。很多新手上来就sudo apt install git装完却败在user.name没配置或者commit时让你猜邮箱又或者git clone一直报Permission denied。这篇文章我就围绕 Ubuntu 安装 Git 这条主线把整个流程从选型到实操再到排障一次性讲透。全文不绕弯子适合刚接触 Linux 的小白也适合那些从 Windows / Mac 迁移过来想摸清 Ubuntu 上 Git 正确姿势的开发者。我会把我自己在多台 Ubuntu 机器上踩过的坑、验证过的命令、以及最后沉淀下来的习惯配置全部写出来。你可以把它当一份“能直接抄作业”的指南按顺序走完你的 Git 环境就能稳稳跑起来。1. 内容整体设计与思路拆解1.1 为什么不是“装个包”这么简单Git 本身是一个版本控制软件但 Ubuntu 上的安装从来不只是apt install git这一行命令的事。背后牵扯到几个层级的决策用什么方式安装、装什么版本、装完怎么进行身份初始化、怎么把本地仓库和远程托管平台打通、以及遇到各种报错时怎么看日志定位问题。我在不同阶段用过不同的安装路径。早期在 Ubuntu 18.04 上直接 apt 装版本停在 2.17.x后来发现某些团队的 CI 脚本要求至少 2.30 以上的特性才支持被迫折腾 PPA也有一次因为实验环境要求 Git 2.39 的某个新功能而系统源里没有最后走源码编译。所以说安装方式选错了后面每一步都别扭。理解这一点后我的第一层设计思路是把安装方式分成三个层次——基础 apt 安装、PPA 追新、源码编译。读者先看自己的实际需求属于哪种再决定走哪条路而不是盲目跟着教程敲命令。第二层设计思路是安装完成后不能停在“git --version 能打印版本”这个表象。真正让 Git 可用需要完成三个动作全局身份配置、SSH 密钥生成并配置到托管平台、以及初始化一个仓库做一次完整提交验证。这三个动作缺一个后续都会出现让人困惑的报错。第三层是排障闭环。我把实际使用中最高频的报错按照“症状 - 原因 - 解决”的结构整理出来方便你遇到问题时直接查。1.2 这套流程适合哪些场景和人群如果你是想在 Ubuntu 上做日常开发、管理个人项目、或接公司代码仓库的开发者这篇文章的流程完全覆盖。尤其是下面三类场景按我的步骤走会省很多时间在 VMware / VirtualBox 虚拟机里装好 Ubuntu准备用来写代码刚入手 Ubuntu 22.04 / 24.04 双系统想把本地的 Git 环境搭好后续配合 Gitee 或 GitHub 使用从其他发行版比如 CentOS或 Windows 迁移过来想快速对齐 Git 环境的配置习惯。另外如果你只会在自己电脑上用 Git、不和远程仓库同步那 SSH 密钥部分可以先跳过但只要涉及推送代码到远程密钥配置就绕不开。文章里我会明确标注哪些步骤是“必需”哪些是“可选但强烈建议”方便你按需执行。2. 核心细节解析与实操要点2.1 安装前必须做的系统准备很多教程上来就让你敲命令但我个人的习惯是先确认两件事当前系统版本和软件源状态。原因很简单Ubuntu 不同版本的软件源里 Git 版本差异很大而且如果你的源没更新过安装的依赖可能不是最新的容易埋下隐患。查看系统版本lsb_release -a查看软件源里 Git 的可用版本在安装前先评估apt-cache policy git这个命令会显示出candidate候选版本也就是你当前源里能装到的最新版本。如果它是 2.25 或更老而你又有明确的新版本需求就不要走 apt 直接装了老老实实看后面的 PPA 方案。我在一台 Ubuntu 18.04 上见过 candidate 只有 2.17而 Ubuntu 22.04 默认源里 Git 是 2.34.1差距还是很明显的。然后更新软件源和系统包索引sudo apt update sudo apt upgrade -y这里解释一下为什么要这两条命令。sudo apt update拉取最新的软件包列表让系统知道源里现在有哪些版本sudo apt upgrade -y把已经安装的软件包升级到软件源里的最新版本。跳过 upgrade 不是不行但后续可能会在编译依赖或其他开发环境搭建时因为基础包太旧而出问题。注意如果你用的是刚装好的 Ubuntu首次 upgrade 甚至会升级内核耗时看网速一般 2 到 10 分钟不等。如果是在生产服务器上升级前记得确认你的应用兼容性我这里默认是个人开发环境直接升问题不大。2.2 三种安装路径的对比与选型逻辑我先把三种方式的核心区别列出来再逐个讲操作步骤安装方式适合场景优点缺点版本示例以 Ubuntu 22.04 为例apt 直接安装绝大多数个人开发、教学环境最简单、依赖自动解决、卸载干净版本偏老受系统和源限制2.34.1PPA 安装git-core/ppa需要较新版本但不想源码编译比官方源新安装方便依赖官方 PPA 维护者的更新节奏可到 2.4x源码编译对 Git 有定制需求、要特定版本完全可控可以打补丁编译耗时长依赖需手动处理任意指定版本我的建议很简单如果你是新手用 apt 装最稳。Git 这个工具版本特性差异主要影响的是新命令参数而非日常的pull、push、commit、branch老版本完全不影响基础使用。等你熟练了真有追新需求再换 PPA 也来得及。2.3 验证安装是否成功的最快方式装完之后不要急着配仓库先跑两个命令git --version which git第一个命令查看 Git 版本确认软件本体装好了第二个命令查看 Git 的可执行文件路径确认它在 PATH 中。输出类似git version 2.34.1 /usr/bin/git看到这两行安装环节就过了。这里忍不住插一句我见过有人装完直接git init报了一堆错才发现git --version都打印不出来基础验证永远值得先做。3. 实操过程与核心环节实现3.1 新人首选apt 安装 Git 全流程这是最稳妥的安装方式。打开终端依次执行sudo apt update sudo apt install git -y-y参数的意思是遇到确认提示自动选 Yes避免安装过程中系统停下来等输入。安装完成后运行git --version如果输出git version 2.34.1不同 Ubuntu 版本会略有差异比如 24.04 默认可能是 2.43.x说明安装成功。这里我要强调一个细节为什么有的教程会让你顺便安装git-core而不是git在 Ubuntu 上git和git-core都会把 Git 主程序装进来但git-core这个包名是历史遗留现在绝大多数情况下装git就够。千万不要两个都装也不要只看标题就装git-core以免版本冲突。3.2 需要追新版本PPA 安装实践如果你发现系统源里 Git 版本不够用可以用这种方法。PPA 是 Ubuntu 的 Personal Package Archive相当于第三方软件源由其他开发者维护。Git 最常用的 PPA 是git-core/ppa。添加 PPA 软件源并安装sudo add-apt-repository ppa:git-core/ppa sudo apt update sudo apt install git -yadd-apt-repository需要系统安装有software-properties-common包如果提示命令不存在先执行sudo apt install software-properties-common -y装完后检查版本大概率能看到 2.4x 的新版。我在 Ubuntu 20.04 上用这个方式把 Git 升到过 2.39.x解决了一个团队需求中需要git switch新语法的兼容问题。顺带提醒一句PPA 装完之后不要急着卸载原来的 Git。如果你之前用 apt 装过 Git再执行上面的apt install git系统会自动升级到 PPA 里的新版本两者用的是同一套包管理机制不存在冲突。这一点和源码编译不一样源码编译装的和 apt 装的会在/usr/local/bin与/usr/bin之间打架。3.3 进阶玩法源码编译安装指定版本需要走源码编译的场景比较少见但偶尔会遇到比如某个项目要求必须用 2.30.0 而 PPA 不够或者你需要让 Git 支持某个特定插件就得在这条路。首先安装编译依赖sudo apt install build-essential autoconf libcurl4-openssl-dev libssl-dev zlib1g-dev libexpat1-dev gettext libtool -y这些依赖分别对应 Git 编译时的不同模块libcurl4-openssl-dev负责 HTTP 传输支持libssl-dev提供加密协议libexpat1-dev用于 XML 解析。缺了任何一项编译时都会报错所以别偷懒。下载源码到临时目录cd /tmp wget https://www.kernel.org/pub/software/scm/git/git-2.42.0.tar.gz tar -zxvf git-2.42.0.tar.gz cd git-2.42.0然后编译安装make prefix/usr/local all sudo make prefix/usr/local install执行完后验证版本git --version源码编译安装后Git 会装在/usr/local/bin/git而 apt 装的在/usr/bin/git。如果git --version显示的还是老版本说明/usr/bin在PATH中的优先级高于/usr/local/bin需要调整环境变量或者把软链接替换掉。提示源码编译看着不难但实际耗时取决于机器性能通常 5 到 15 分钟不等。除非你是做 Git 二次开发或者有特殊需求否则不建议为了一两个新特性就去源码编译。我后来大部分时候还是回归 PPA 方案省心得多。3.4 安装完成后必做的三个硬配置3.4.1 配置 user.name 和 user.email这是 Git 环境配置中最关键、也最容易被新手忽视的一步。没有配置 user.name 和 user.email你第一次 commit 时会报错或者生成的提交里没有正确作者信息在公司协作中会导致代码提交记录无法追溯到人。配置全局身份git config --global user.name 你的名字 git config --global user.email 你的邮箱这两条命令的执行效果是写入~/.gitconfig文件。你也可以直接编辑这个文件效果等同nano ~/.gitconfig配置完成后验证git config --global --list输出中应该能看到user.name你的名字 user.email你的邮箱为什么用--global因为这是全局配置对当前系统用户下的所有仓库生效。如果你同时有多个 Git 身份比如公司邮箱和个人邮箱可以在某个具体仓库目录下单独设置--local覆盖全局值cd /path/to/repo git config --local user.email companyexample.com这个局部配置只对当前仓库生效不影响其他项目。3.4.2 生成 SSH 密钥并配置到托管平台这一步是为了让你不用每次 push / pull 都输账号密码。Git 支持 HTTPS 和 SSH 两种远程协议。HTTPS 每次都要输用户名密码但可以配置 credential helper 记住SSH 则通过密钥对进行免密认证一次配置长期有效。生成密钥ssh-keygen -t ed25519 -C 你的邮箱这里我用的是ed25519算法比传统的 RSA 更安全、密钥更短、生成速度更快。如果你的系统或托管平台不支持 ed25519多数现代平台都支持了可以退回去用ssh-keygen -t rsa -b 4096 -C 你的邮箱执行后会有交互提示建议一路回车使用默认路径~/.ssh/id_ed25519这样就无需额外配置~/.ssh/config。如果你想设置密码保护私钥可以输入一个 passphrase我建议设置这样即使私钥被别人拷走不知道 passphrase 也没法用。生成完成后查看公钥cat ~/.ssh/id_ed25519.pub复制输出内容登录你的 Gitee 或 GitHub在“设置” - “SSH 公钥”里粘贴保存。然后测试连接ssh -T gitgitee.com如果输出欢迎信息类似Hi 你的名字! Youve successfully authenticated, but GITEE.COM does not provide shell access.说明 SSH 密钥配置成功。GitHub 对应命令是ssh -T gitgithub.com3.4.3 让 Git 记住 HTTPS 密码如果你更喜欢用 HTTPS 协议拉代码不想每次输密码可以开启 credential helpergit config --global credential.helper store这样第一次输入密码后会明文保存在~/.git-credentials文件中后续免输。在个人电脑上没问题在公司多人共用电脑上就不建议了明文存凭据风险偏大。3.5 首次提交实操把仓库跑通配置完上面这些就可以初始化一个仓库走完整流程了。以创建一个新项目为例mkdir ~/my-first-repo cd ~/my-first-repo git init创建并编写一个测试文件echo # My First Repo README.md添加所有文件并提交git add . git commit -m init: 初始化项目此时如果前面身份配置正确应该看到类似输出[master (root-commit) abc1234] init: 初始化项目 1 file changed, 1 insertion() create mode 100644 README.md这里我做了一个我平时非常推荐的动作——在首次提交时使用规范的 commit message。我习惯用init:作为前缀在后续项目中用feat:、fix:、docs:等标签区分提交类型。这在多人协作时梳理变更历史非常有用。如果需要推送到远程仓库在 Gitee/GitHub 上新建一个空仓库然后添加远程地址并推送git remote add origin gitgitee.com:你的用户名/仓库名.git git branch -M main git push -u origin main注意现在 Git 的新仓库默认分支名可能是master也可能是main取决于你的 Git 版本和全局配置。git branch -M main的作用是把当前分支改名为main并强制覆盖同名分支第一次推送时这么写稳妥。-u参数将本地分支和远程分支建立关联之后直接git push即可不用再带远程名和分支名。4. 生产环境下的 Git 细节配置4.1 换行符与文件命名习惯Linux 和 Windows 的换行符不同Linux 使用LFWindows 使用CRLF。如果同一个仓库在两个系统间切换使用Git 可能会出现所有文件都被标记为“已修改”的诡异现象。这在 Ubuntu 上安装 Git 后尤其常见——因为大部分人是从 Windows 迁过来的。解决办法是一行配置git config --global core.autocrlf input这个配置的意思是提交时把CRLF转换为LF检出时不转换。Linux 和 macOS 环境下就用input。Windows 环境下通常建议true检出时转回 CRLF或false完全不做转换。另一种更规范的做法是在仓库根目录添加.gitattributes文件。我一般会在项目里放上* textauto *.sh text eollf *.bat text eolcrlf这样无论谁在什么系统上克隆这个仓库Git 都会根据.gitattributes自动处理换行符比个人 config 更可靠因为它跟随仓库走不依赖每个人的本地设置。4.2 中文文件名显示乱码与转义问题在 Ubuntu 终端里git status看到中文文件名显示成八进制转义序列是不少人的心头病。其实这不是乱码而是 Git 默认对非 ASCII 字符做了转义显示。解决方法是git config --global core.quotepath false设置完之后中文文件名就能正常显示了。同时建议确认终端编码为 UTF-8export LANGen_US.UTF-8或者直接在.bashrc中写入echo export LANGen_US.UTF-8 ~/.bashrc source ~/.bashrc这两个操作配合中文文件名和中文 commit message 都能正常显示。4.3 常用别名配置日常操作中很多命令输入频率很高但字符数不少。我习惯在.gitconfig中配几个别名提升效率git config --global alias.st status git config --global alias.co checkout git config --global alias.br branch git config --global alias.cm commit git config --global alias.lg log --oneline --graph --all --decorate配完之后git st等价于git statusgit lg能输出漂亮的分支提交树。这些别名纯属个人习惯增强不影响 Git 本身的任何行为。4.4 默认编辑器与差异工具设置Git 在某些场景会调用编辑器比如git commit不带-m参数时、或者git rebase -i交互式变基时。Ubuntu 默认可能调用 nano如果你不习惯可以切换到 vim 或 VS Codegit config --global core.editor vim如果是新手我更推荐用 VS Code 作为编辑器出错时会直观很多git config --global core.editor code --wait同时设置差异工具diff tool和合并工具merge toolgit config --global diff.tool vscode git config --global difftool.vscode.cmd code --wait --diff $LOCAL $REMOTE git config --global merge.tool vimdiff这些配置不是必须的但会显著提升你的 Git 使用体验。我用 vimdiff 做冲突合并已经很多年了效率确实高。5. 常见问题与排查技巧实录5.1 执行 git commit 时报错提示输入 user.name / user.email这是新手最常见的错误报错内容类似*** Please tell me who you are. Run git config --global user.email youexample.com git config --global user.name Your Name原因就是前面说过的身份信息没配置。按提示在终端执行git config --global user.name 你的名字 git config --global user.email 你的邮箱然后重新 commit 即可。如果你不确定之前是否配置过先运行git config --global --list这个坑之所以高频是因为很多人会跳过“验证配置”这一步直接跳到初始化仓库和提交代码。我的建议是装完 Git 的第一个操作就是配全局身份不要留到出错再补救。5.2 克隆仓库时提示 Permission denied (publickey)症状是执行git clone gitgitee.com:xxx/xxx.git时报Permission denied (publickey).大多数情况下是密钥没有正确配置到 Gitee / GitHub或者本地根本没有生成密钥。排查顺序如下ls ~/.ssh/id_ed25519.pub如果文件不存在回到第 3.4.2 节生成密钥。存在则看公钥内容cat ~/.ssh/id_ed25519.pub对比你粘贴在托管平台上的公钥是否一致。还有一个小概率原因ssh-agent没加载密钥用这个命令修复eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519如果依然失败可以加上调试参数排查ssh -vT gitgitee.com输出末尾通常会给出有价值的提示比如Offering public key或send_pubkey_test。5.3 apt 安装完执行 git 提示“command not found”这是极端情况但我也遇见过。表现为sudo apt install git成功但关闭终端再打开后执行git提示找不到命令。大概率是 shell 没有重新加载 PATH或者是你在 sudo 模式下安装的路径和普通用户 PATH 不一致。先确认安装是否成功sudo which git如果这个命令能输出/usr/bin/git说明装好了。普通用户找不到要么是~/.bashrc里面 PATH 被改错了要么是当前 shell 没刷新。解决办法hash -r这个命令重新扫描 PATH 中的命令缓存。如果不行就用exit退出终端再重新进入。还有人遇到的是环境变量 PATH 配置出问题导致/usr/bin不在 PATH 里。检查echo $PATH正常输出应当包含/usr/bin。如果确实被改坏了在~/.bashrc里追加export PATH/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PATH再执行source ~/.bashrc。这一招在 Ubuntu 上修 PATH 错乱特别管用。5.4 Git push 时报“fatal: unable to access ... Could not resolve host”这个报错本质上和 Git 无关是网络层面的问题。Could not resolve host说明 DNS 解析失败或者代理配置干扰了 Git 的访问。排查步骤ping gitee.com如果 ping 不通说明 DNS 有问题。查看 DNS 配置cat /etc/resolv.conf如果里面有明显的错误 DNS 服务器可以修改/etc/resolv.conf或改用系统网络设置中的 DNS。我在 Ubuntu 22.04 上还遇到过一个情况终端里设置了http_proxy环境变量指向一个已经关闭的代理导致 Git 一直访问失败。解决办法是确认环境变量env | grep -i proxy如果有输出说明代理环境变量在场要么修正代理地址要么清掉unset http_proxy unset https_proxy5.5 升级 Git 后原有仓库报错“detected dubious ownership”这个问题出现的概率不低尤其当你从旧版本 Git 升级到新版本或者通过源码编译替换了 apt 版 Git 时。报错信息类似fatal: detected dubious ownership in repository at /path/to/repo这其实是 Git 的目录所有权安全检测机制在起作用。新版 Git 增加了对仓库目录所有者身份的校验如果仓库所有者不是当前用户或系统账号就会拦截执行。解决办法有几种sudo chown -R $(whoami) /path/to/repo把仓库目录的所有者改成当前用户这是最彻底的方案。如果你确认目录归属没问题例如它是系统目录下的合法工程可以临时关闭这个安全检测git config --global --add safe.directory /path/to/repo我个人的建议是先 chown不要关检测。这个检测机制是有价值的直接关掉会失去一层保护。5.6 换了新机器后 clone 慢或拉不下来不少人在新装 Ubuntu 上 clone 大型仓库时发现速度很悲剧或者文件差异很大时 pull 卡死。这里有一个和 Git 无关但很实际的原因默认的压缩和 delta 算法对大型仓库压力很大。可以尝试调整 post-buffer 和 compressiongit config --global http.postBuffer 524288000 git config --global core.compression 0http.postBuffer设置 HTTP 协议下推送缓冲区的最大值单位是字节这里设置为 500MB适合推送大仓库或者使用 HTTP 协议的场景。core.compression设为 0 表示不压缩CPU 占用率低一些但传输量会增大适合 CPU 性能弱的机器。这两个参数不是标准答案但实测在某些网络环境下有效。5.7 常见问题速查表症状常见原因解决方向commit 报错提示输入身份user.name / user.email 未配置git config --global user.name/user.emailclone 提示 Permission denied公钥未配置或 SSH 密钥未加载生成并添加公钥ssh-add加载私钥git 命令找不到PATH 被改坏或 shell 缓存hash -r刷新检查$PATH中文文件名显示转义序列core.quotepath 未关闭git config --global core.quotepath false文件全部标记为已修改CRLF 换行符混用配置core.autocrlf input或.gitattributesclone 时报 Could not resolve hostDNS 问题或代理环境变量错误检查/etc/resolv.conf清除http_proxy升级后报 dubious ownership新版本目录所有权安全检测chown更换归属或safe.directory添加白名单大仓库 pull 卡死缓冲区过小或压缩压力大调整http.postBuffer和core.compressionpush 被拒绝提示 remote rejected远程分支有提交而本地落后git pull --rebase后再 push这张表是我平时排查问题的第一入口。遇到报错先对症状再看原因方向基本都能定位到具体章节。6. 收尾经验分享这篇文章写到这里Git 本体已经装好、配好、排障手段也齐了。最后分享一个我自己摸索了很久才养成的习惯每次装完 Git 后我会顺手把这几个高频命令的习惯配置固化进.bashrc里而不是用一次配一次。比如export GIT_EDITORvim export GIT_SSH_COMMANDssh -o ServerAliveInterval60第一条把默认编辑器固定为 vim避免某些工具弹出莫名编辑器第二条让 SSH 连接每 60 秒发一次心跳包防止长时间操作时连接被服务器掐掉。这两条环境变量配合本文章前面的配置在真实开发环境中非常省心。在我自己的多台 Ubuntu 机器上这套安装与配置流程反复使用了很多次每次都能把 Git 环境在十分钟内搭利索。如果你在实操中遇到文章里没覆盖到的怪问题建议第一时间开调试模式跑一次GIT_TRACE1它会把 Git 内部执行细节全部打印出来很多看似玄幻的报错只要看到调试输出原因就清楚了一大半。
阅读完成 · 觉得有帮助？
