1. 为什么我建议在WSL里用Git而不是Windows原生很多朋友第一次听到WSL下配置Git会觉得多此一举Windows上装个Git for Windows不香吗命令行里敲git一样能用还有 TortoiseGit 这种图形界面双击就能提交。说实话我早年间也是这么想的直到有一次在一个混合开发环境里连续踩了三个坑才彻底转到WSL路线。那次项目是一个嵌入式Linux相关的仓库代码里大量用到符号链接还混着很多Linux shell脚本。Windows上克隆下来符号链接直接失效脚本的换行符变成CRLF一执行就报bad interpreter。我折腾了一下午最后发现问题出在Git for Windows的core.autocrlf默认行为上。后来我换到WSL里操作同样的仓库没有任何问题。WSLWindows Subsystem for Linux本质上是Windows内置的一个轻量级Linux环境。你可以在里面装真实的Linux发行版比如Ubuntu、Debian用原生的Linux工具链操作Git仓库。对于做嵌入式、后端服务、数据工程或者任何最终要跑在Linux上的项目这是巨大的优势——你在本地操作的Git行为和线上服务器几乎一致避免掉本地好好的一上服务器就出问题这种经典翻车。这篇文章我把自己在WSL下配置Git的完整过程梳理一遍从WSL环境的准备、Git安装、身份配置、SSH密钥、换行符处理到和Windows宿主机互操作、VSCode联动最后是日常用得上的排查命令。内容比较全新手可以跟着一步步走老手可以直接跳到第7章看问题排查。2. WSL环境准备先把Linux子系统利索地装起来配Git之前得先有一个能用的WSL环境。这一步看着简单但实际装的时候不少人会卡住尤其在某些网络环境下wsl --install下载发行版镜像特别慢或者中途报错退出。2.1 WSL的安装方式与版本选择先检查你的Windows版本。Win10 2004及以上、Win11都支持WSL 2。最简单的安装方式是在管理员权限的PowerShell里执行wsl --install这条命令默认装的是Ubuntu最新LTS版本并且会同时启用WSL 2所需的虚拟机平台组件。装完重启系统会提示你创建Linux用户和密码。如果你不想用默认的Ubuntu可以先用这条命令看看可选发行版wsl --list --online输出里能看到 Ubuntu、Ubuntu-22.04、Debian、Kali Linux 等多个发行版。比如想装Debianwsl --install -d Debian这里我多说一句选型的事。我在网上看到过一个热搜词是wsl 2 debian 13 安装步骤Debian 13属于较新的滚动版本软件源比稳定版激进如果本身不是Debian重度用户建议还是老老实实选Ubuntu LTS。原因是社区教程多、出问题好搜、apt源配置资料丰富Git这类工具在Ubuntu上永远是最新稳定的版本之一。对绝大多数人来说Ubuntu就是WSL下的最优解。2.2 安装WSL时的常见坑与路径迁移WSL默认会把发行版文件放在C盘系统盘。很多朋友C盘本来就紧张装完WSL没几天发现Windows系统盘又红了大半。我自己的做法是装完立刻把发行版迁到D盘。先看当前安装的发行版列表wsl --list --verbose确认名字后执行导出和注销wsl --export Ubuntu D:\wsl\ubuntu-backup.tar wsl --unregister Ubuntu注意unregister会删除当前发行版的所有数据所以一定要先导出备份。然后再重新导入到D盘wsl --import Ubuntu D:\wsl\ubuntu D:\wsl\ubuntu-backup.tar --version 2导入后默认用root登录可以用ubuntu config --default-user 你的用户名恢复原来的默认用户不同发行版命令略有差异取决于发行版自带的config工具。另一个常见问题是wsl --install卡在下载阶段或者报错WslRegisterDistribution failed。这种一般是网络波动或者Windows组件未完整安装。处理思路有几个先把Windows更新和可选功能里的适用于Linux的Windows子系统、虚拟机平台两项确认开启再检查BIOS里虚拟化是否打开任务管理器-性能-CPU看虚拟化状态最后再执行wsl --install --web-download这个选项会让它走在线下载流程而不是用内置包能绕开一些本地组件损坏的问题。2.3 基础环境调整与软件源更换装好发行版后第一件事是把软件源换成国内镜像。为什么因为默认源在国外执行apt update时速度极其感人装个Git要等半天。这里我顺带解释一下为什么装Git要先换源Git本体很小但它的依赖比如ca-certificates、openssh-client、curl在Ubuntu里是通过apt包管理器统一安装的如果源慢整个安装链路都会卡住。Ubuntu 22.04以上版本改源很方便sudo sed -i s/archive.ubuntu.com/mirrors.aliyun.com/g /etc/apt/sources.list sudo apt update或者用清华源也一样。改完源再执行apt update速度会快很多。这是我在WSL下做的第一件标准化操作后续所有工具安装的体验都会好很多。3. 在WSL中安装Git比你想的更简单WSL里的Git安装非常直白因为Ubuntu官方仓库里就有现成包。但正因为简单反而很多人忽略了版本检查、依赖完整性的问题。3.1 安装命令与版本选择打开WSL终端在Windows命令行输入wsl即可进入执行sudo apt update sudo apt install git -y装完验证git --version一般来说Ubuntu 22.04自带仓库里的Git是2.34左右24.04则是2.43以上。这个版本对日常使用完全够了。这里我想特别提一个点尽量不要用apt install git装到一半就中断更不要用sudo apt upgrade时的回答去跳过大版本升级。Git在WSL里的依赖关系比较敏感如果你之前装过一些开发工具apt可能提示需要同时升级一大堆库这时候直接确认让它整体升级就好不要用--no-install-recommends去精简否则后续可能缺git-lfs或者openssh-client这类关键组件。如果你需要更新的Git版本比如要用最新的浅克隆功能可以用 launchpad 的 git-core PPAsudo add-apt-repository ppa:git-core/ppa sudo apt update sudo apt install git -y不过我实际操作下来官方源里的版本足够用了除非你有明确需求否则不必折腾PPA。3.2 验证Git依赖与最小可用配置装完Git检查一下核心组件是否都在git --version which git ssh -V这里ssh -V是为了确认OpenSSH客户端存在后面配SSH密钥要用。如果提示没有ssh就装sudo apt install openssh-client -y再顺便装上Git LFS现在很多仓库都用了大文件存储sudo apt install git-lfs -y git lfs install这一步很多人会漏掉。等到git clone一个大仓库时发现LFS文件全是指针文件再回头装就晚了。热搜词里也有git lfs clone卡住的问题后面排查章节我会细说。Git装完先做一次空跑验证——随便建个目录试一下mkdir ~/git-test cd ~/git-test git init git status能正常输出On branch master或者提示初始分支名就说明Git已经能跑了。这时候再配置身份信息就是下一章节的事。4. Git核心配置身份、换行符与默认行为安装只是第一步真正决定你用起来顺不顺手的是初始化配置。很多人装完Git直接就开始clone结果提交记录里用户名是一串乱码或者仓库里所有文件都被标记成修改状态就是没认真做配置这步。4.1 用户身份配置这不是给Git看的是给协作的人看的Git每次提交都会把user.name和user.email写进提交记录。如果没配置Git会在你第一次commit时提示你配置或者干脆用系统用户名生成一串奇怪的身份信息。在WSL里执行git config --global user.name 你的名字 git config --global user.email 你的邮箱验证git config --global --list这里我有一个从实际经历里总结的建议email填你注册代码托管平台GitHub/Gitee/公司GitLab时用的邮箱和账号保持一致。否则你提交的记录不会关联到你的账号头像别人看你提交历史时显示的是未知作者影响Code Review时的追溯效率。我就见过一个同事在Gitee上代码提交者名字显示不出来查了半天原因是他在WSL里配的邮箱和Gitee账号邮箱不一致。4.2 换行符问题CRLF/LF 是WSL里最大的隐性坑这是WSL下Git最容易踩的坑也可能是全网搜索WSL Git被问得最多的问题之一。简单解释一下Windows系统里文本文件的换行是\r\nCRLFLinux和macOS用的是\nLF。Git在设计时就考虑到跨平台换行所以有了core.autocrlf这个开关。它的三个取值true提交时把CRLF转成LF检出时把LF转成CRLFinput提交时转LF检出不动false不做任何转换在Windows原生的Git for Windows里默认core.autocrlftrue这对纯Windows项目友好。但在WSL里你的目标是让仓库内容保持Linux习惯如果还用true检出的shell脚本会带CRLF一执行就报错。所以正确做法是git config --global core.autocrlf input更推荐的方式是用.gitattributes文件来按仓库声明比如文本文件统一LF、二进制文件标记-text但对于个人全局配置input是相对安全的中间值它保证提交进仓库的内容永远是LF又不会强制改你本地已有的文件。如果仓库已经被错误换行符污染了表现为git diff显示整个文件都被改动第一件事先看是不是换行符问题git config --global core.autocrlf input git add --renormalize .这条add --renormalize是Git 2.16以后的新特性会把工作区文件按当前换行符设置重新规范化我在处理换行符混乱的仓库时用过好几次效果明显。4.3 默认分支名与其他全局配置Git 2.28之后支持自定义初始分支名建议设成maingit config --global init.defaultBranch main顺手把push默认行为改成更安全的simple这本来也是新版本默认值git config --global push.default simple再看一个容易忽略的配置pull时默认的合并策略。有人喜欢pull.rebase有人习惯pull.ff-only。我个人的习惯是git config --global pull.rebase false这样默认git pull是merge行为对新手更友好不容易产生rebase带来的历史重写困惑。当然如果你团队规范要求线性历史那就改成true。这里没有统一标准结合团队习惯来。5. SSH密钥配置与免密推送有了身份和换行符配置Git已经能正常提交了。但日常大家更多是跟远程仓库打交道那就绕不开SSH密钥这件事。搜热词里ssh认证失败 gitgit配置gitee密钥频繁出现说明这是大家卡壳的重灾区。5.1 为什么推荐SSH而不是HTTPSHTTPS方式clone时每次push都要输账号密码虽然可以靠凭证管理器记住但WSL里的Git默认不会自动保存Windows凭据我得手动配credential helper才能免密。相比之下SSH密钥机制一劳永逸本地生成私钥公钥放到GitHub/Gitee等平台之后push/pull完全不需要再输任何密码。所以我在WSL下清一色用SSH协议操作远程仓库。下面这个步骤序列是固定套路ssh-keygen -t ed25519 -C 你的邮箱回车后会问你保存路径和密码短语passphrase。这里我建议保存路径用默认的~/.ssh/id_ed25519passphrase可以设一个简单的也可以直接回车留空。如果设了passphrase每次ssh操作都要输一遍虽然安全但很烦。日常开发机里留空就行笔记本这种容易丢的设备再考虑加passphrase。生成后查看公钥内容cat ~/.ssh/id_ed25519.pub把这段内容复制到Gitee的SSH公钥设置页或者GitHub的SSH keys里保存。然后测试ssh -T gitgitee.com看到类似Hi xxx! Youve successfully authenticated的输出说明SSH通道已通。然后clone就变成git clone gitgitee.com:username/repo.git全程不用输密码。5.2 多账号与config文件GitHub、Gitee、GitLab共存很多人不只用一个平台。你可能在Gitee有公司项目GitHub有自己的开源仓库GitLab还有客户项目。这时候如果所有平台都用同一个密钥问题不大但如果你希望不同平台用不同身份比如公司邮箱和个人邮箱分开就需要在~/.ssh/config里做分流。我的配置文件长这样Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee对应的需要为每个平台生成单独密钥ssh-keygen -t ed25519 -C github邮箱 -f ~/.ssh/id_ed25519_github ssh-keygen -t ed25519 -C gitee邮箱 -f ~/.ssh/id_ed25519_gitee然后把对应的.pub内容分别添加到对应平台。这里有一个小细节生成多把密钥时每次要指定不同的-f路径否则会覆盖之前的密钥。我第一次配多账号时没指定路径直接把GitHub的密钥覆盖了Gitee的后来两个平台互相认证失败排查了半小时才发现。另外多账号场景下邮箱配置要同步注意。一个仓库里可以用git config user.email覆盖全局配置防止提交身份混用。5.3 密钥权限问题的排查习惯SSH认证失败很多时候不是密钥内容错了而是权限不对。OpenSSH对私钥文件的权限非常严格如果~/.ssh/id_ed25519的权限是644它会拒绝使用这把密钥并提示Permissions too open。正确的权限应该是chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519顺便把~/.ssh/known_hosts权限也修一下避免第一次连接时被提示文件权限异常chmod 644 ~/.ssh/known_hosts每次碰到SSH认证失败我都会按这个顺序排查先ssh -T看错误信息再检查密钥权限再看config文件写没写对最后确认公钥是否真的贴到了平台。90%的问题都能在这几步里解决。6. WSL与Windows互操作跨文件系统操作Git仓库WSL和Windows之间可以互相访问文件这是WSL最实用的特性之一。但具体到Git操作这里面的门道比表面看起来要多操作不当会导致仓库慢得离谱甚至文件损坏。6.1 别在 /mnt/c 下跑Git除非你清楚代价WSL里访问Windows盘符的路径是/mnt/c/。你可以直接cd /mnt/c/Users/你/项目然后在里面执行Git命令这确实很方便——解决了Windows上的项目想用Linux工具链的痛点。但代价是性能损失巨大。原因是WSL访问Windows文件系统要走9P协议跨文件系统读写的I/O性能大概相当于本地Linux文件系统的几十分之一。我自己做过一个简单测试在/mnt/c下对一个中等规模仓库执行git status耗时2秒以上把同一份仓库复制到~/workspaceWSL原生文件系统里同样git status几乎瞬间完成。所以我的建议非常明确WSL里开发的项目仓库目录统一放在Linux文件系统下比如~/workspace、~/code。Windows侧访问WSL文件可以通过\\wsl$\Ubuntu\home\用户名\workspace这个UNC路径在资源管理器里直接映射成网络路径。两边互不打扰速度也快。热搜词里有一类wsl访问宿主机端口和wsl d盘的话题其实是两件事。如果你只是需要偶尔在WSL里操作一下D盘的某个文件用/mnt/d/临时访问完全可以但如果你要在里面长期开发务必copy到Linux侧。这条是我在WSL里用Git最重要的一条经验没有之一。6.2 Git仓库里出现一堆修改未暂存的诡异状态Windows和Linux文件系统还有一个差异权限位。WSL挂载Windows盘时默认给所有文件分配了rwx权限组合而且/mnt/c下的文件全部显示为755。这样一来用Windows工具比如IDE和WSL轮番操作同一个仓库时经常出现明明什么都没改Git却提示一堆文件都是modified的情况而且改的全是mode 100644 - 100755这种权限变化。网上的解决办法千篇一律git config core.filemode false。确实有效git config --global core.filemode false这行配置的意思是Git不追踪文件权限位的改变。在纯WSL环境里一般不需要但在Windows和WSL混用、或者仓库放在/mnt/c下时就很重要。我建议WSL用户直接全局关掉省心。6.3 VSCode WSL现在最顺手的Git操作姿势如果你问我现在WSL里用Git最舒服的界面是什么我的答案不是命令行而是VSCode的Remote-WSL插件。在VSCode里装上Remote - WSL扩展然后用code ~/workspace这样的命令从WSL终端里直接打开文件夹VSCode会自动进入WSL模式。此时VSCode左侧的源代码管理面板操作Git解析的是WSL里的git命令走的是WSL文件系统完全没有前面说的跨盘性能问题。用VSCode操作Git的好处是diff对比可视化、冲突解决界面友好、Staging操作点一下就完成这些比纯命令行对新手友好太多。而且底层还是WSL里的Git行为一致不用担心两套环境打架。如果你的VSCode还不能从WSL启动检查一下是不是没装扩展、或者命令行code没注册。一般在WSL里首次打开VSCode时它会自动装一个server组件装完就能互通了。7. 常见问题与排查实录最后这部分我把这几年在WSL下用Git遇到的高频问题整理成一个速查表。每一条都来自真实排障经历不是网上抄来的标准答案。7.1 SSH认证失败Permission denied (publickey)现象git clone gitgithub.com:xxx/xxx.git时报Permission denied (publickey)。排查顺序先确认客户端用的是哪把密钥ssh -vT gitgithub.com看输出里的Offering public key路径。检查公钥是否已添加到平台账号注意别把私钥内容贴上去。复查~/.ssh/config有没有拼写错误比如HostName写成了域名后缀带空格。检查权限ls -l ~/.ssh/id_ed25519确认是-rw-------。我的经验见过最多的情况其实是用户先用了Windows的ssh-keygen生成密钥然后又把密钥拷到WSL里用两边的known_hosts和权限互相干扰导致验证一直失败。解决方案很简单——在WSL里重新生成一份专属密钥不用Windows那套。7.2 中文文件名和提交信息乱码现象git status显示中文文件名是一串八进制转义\344\270\255\346\226\207或者提交信息里的中文变成乱码。原因Git默认对非ASCII文件名做转义显示终端编码不匹配时中文提交信息也会乱。解决git config --global core.quotepath false git config --global i18n.commitEncoding utf-8 git config --global i18n.logOutputEncoding utf-8第一条core.quotepath false是我最推荐的设完之后中文文件名正常显示。后面两条是提交信息的编码声明WSL默认locale一般已经是UTF-8多数情况不配也行但如果遇到过乱码就加上。7.3 明明改了文件git status 却没有任何反应在WSL下用Vi或Vim编辑过文件后有时发现Git不认为文件有变化。第一反应别去重装Git先看文件时间戳和内容编码是不是被编辑器改成了UTF-8 BOM。BOM头在Git看来是内容变化但你肉眼看不到。这种场景的处理方式是git diff --stat git diff如果diff为空但git status报modified多半是换行符或BOM问题。用git add --renormalize .重新规范化一次再看。再不行就直接看文件的十六进制头xxd 文件名 | head -n 3有ef bb bf开头就是BOM去掉即可。7.4 git clone 中途卡住或者LFS文件拉不动搜热词里出现过git lfs clone卡住这个我踩过。git lfs clone卡住常见原因是LFS下载走的是独立的HTTP请求进度条不动是因为有些LFS服务端响应慢或者网络对某些CDN节点不稳定。处理办法先尝试普通git clone然后用git lfs pull单独拉LFS文件这样能把LFS下载失败和仓库本身的问题分开。设置LFS超时时间git config --global lfs.activitytimeout 30如果卡在某个文件一直重试可以看看是不是单个LFS文件太大。git lfs env可以查看LFS环境信息确认endpoint地址是否正确。7.5 系统休眠后WSL里的Git仓库状态异常这个非常隐蔽。Windows休眠唤醒后WSL的时钟可能漂移导致Git认为某些文件的修改时间异常git status出现大量modified假象。还有更糟的docker、进程、文件锁状态全部错乱。处理方式就一条在Windows终端执行wsl --shutdown然后重新进WSL。这个命令能强制重启WSL后台虚拟机基本能解决所有休眠唤醒后环境诡异的问题。我已经养成习惯了每次Windows唤醒后感觉终端操作卡顿先wsl --shutdown再重开。7.6 全局配置的温馨小提醒最后说一个我踩过几次坑之后的习惯所有Git全局配置我都在WSL里配一份Windows原生Git也配一份但两边的配置保持一致。具体来说WSL里的配置文件在~/.gitconfigWindows的在C:\Users\你\.gitconfig。如果你在WSL里改了自己的~/.gitconfigWindows侧不会同步。所以遇到WSL里配置配了Windows下commit还是旧名字这种情况别怀疑Git坏了就是两边配置文件各管各的。确认当前生效的配置git config --list --show-origin这条命令会把每条配置项的来源文件路径打出来。看到来源是/home/xxx/.gitconfig还是C:/Users/xxx/.gitconfig你瞬间就知道自己改的是哪一份了。我个人在实际操作中的体会是WSL下配置Git这件事本质不是在装工具而是给自己建立一个接近生产环境的开发习惯。很多在Windows上常见的换行符、权限、路径问题在WSL里天然就不存在了而WSL本身又不像一台独立虚拟机那样割裂——文件能在Windows里编辑端口能被Windows程序访问IDE能无缝接入。所以如果你还在Windows和Linux两套环境之间来回折腾Git不如花一晚上把WSL这套环境搭好后面省下的时间绝对超过安装成本。