企业官网建设流程全解析

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里操作，同样的仓库，没有任何问题。

WSL（Windows 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 等多个发行版。比如想装Debian：

wsl --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 PPA：

sudo 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\n（CRLF），Linux和macOS用的是\n（LF）。Git在设计时就考虑到跨平台换行，所以有了core.autocrlf这个开关。它的三个取值：

• true：提交时把CRLF转成LF，检出时把LF转成CRLF
• input：提交时转LF，检出不动
• false：不做任何转换

在Windows原生的Git for Windows里，默认core.autocrlf=true，这对纯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之后支持自定义初始分支名，建议设成main：

git 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认证失败 git""git配置gitee密钥"频繁出现，说明这是大家卡壳的重灾区。

5.1 为什么推荐SSH而不是HTTPS

HTTPS方式clone时每次push都要输账号密码，虽然可以靠凭证管理器记住，但WSL里的Git默认不会自动保存Windows凭据，我得手动配credential helper才能免密。相比之下，SSH密钥机制一劳永逸：本地生成私钥，公钥放到GitHub/Gitee等平台，之后push/pull完全不需要再输任何密码。

所以我在WSL下清一色用SSH协议操作远程仓库。下面这个步骤序列是固定套路：

ssh-keygen -t ed25519 -C "你的邮箱"

回车后会问你保存路径和密码短语（passphrase）。这里我建议：保存路径用默认的~/.ssh/id_ed25519，passphrase可以设一个简单的，也可以直接回车留空。如果设了passphrase，每次ssh操作都要输一遍，虽然安全，但很烦。日常开发机里留空就行，笔记本这种容易丢的设备再考虑加passphrase。

生成后，查看公钥内容：

cat ~/.ssh/id_ed25519.pub

把这段内容复制到Gitee的"SSH公钥"设置页，或者GitHub的"SSH keys"里，保存。然后测试：

ssh -T git@gitee.com

看到类似Hi xxx! You've successfully authenticated的输出，说明SSH通道已通。然后clone就变成：

git clone git@gitee.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秒以上；把同一份仓库复制到~/workspace（WSL原生文件系统）里，同样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 git@github.com:xxx/xxx.git时报Permission denied (publickey)。

排查顺序：

1. 先确认客户端用的是哪把密钥：ssh -vT git@github.com，看输出里的Offering public key路径。
2. 检查公钥是否已添加到平台账号，注意别把私钥内容贴上去。
3. 复查~/.ssh/config有没有拼写错误，比如HostName写成了域名后缀带空格。
4. 检查权限：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里的配置文件在~/.gitconfig，Windows的在C:\Users\你\.gitconfig。如果你在WSL里改了自己的~/.gitconfig，Windows侧不会同步。所以遇到"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这套环境搭好，后面省下的时间绝对超过安装成本。