企业官网建设流程全解析

1. 先把“VS Code 连接已有仓库”这件事拆开看

日常交流里，“链接”和“连接”经常被混着用，实际想做的事无非两类：一类是把远端已经存在的仓库拉到本地，让 VS Code 打开就能读能改能提交；另一类是本地早就有一堆代码，只是还没跟远端那个仓库建立关系，需要在 VS Code 里把这条“线”接上。这两件事在命令行里是两条完全不同的路径，前者是git clone，后者是git init+git remote add，但很多人在 VS Code 里点来点去，把两者搞混，最后出现“明明代码在，为什么推不上去”“明明仓库存在，为什么 VS Code 说找不到”这类问题。我用 VS Code 配合 Git 干活有七八年了，从早期只能靠命令行、到现在图形界面基本够用，中间踩过的坑足够写满一个小本子。这篇就把“VS Code 连接已有仓库的代码”这件事从头拆到尾：环境怎么配、两种场景分别怎么走、图形界面里哪些按钮能点哪些别乱点、报错怎么查。不管你是刚接手一个别人留下的项目，还是要把自己写了一半的本地工程挂到一个已有的远端仓库上，下面这些操作都能直接照着做。

我先把结论放前面：绝大多数“连不上”的问题，都不是 VS Code 的问题，而是 Git 的身份、凭证、远端地址、分支追踪关系这四样里有一样没对。VS Code 只是一个把 Git 命令包装成按钮的外壳，按钮点下去执行的还是那几条命令，所以理解命令本身，比背界面位置有用得多。这也是我后面每个步骤都贴命令的原因——界面会随版本变，命令不会。

1.1 三种典型场景，先对号入座

在动手之前，花三十秒判断自己属于哪一种，能省掉后面半小时的瞎折腾。这三种场景的前置条件、操作顺序、容易出错的点完全不一样，混着做必然卡住。

场景 A 是最省事的，克隆下来什么都是对的，分支追踪关系 Git 自动帮你建好了。真正麻烦的是 B，因为两边的提交历史各自独立，Git 会认为这是两条毫不相干的线，默认不允许合并。C 看起来简单，但很多人忘了-u参数，结果后面在 VS Code 里点“同步”按钮时，它不知道要推到哪个远端分支，报错信息又写得含糊，很容易卡住。

1.2 为什么这件事看起来简单，做起来处处是坑

从操作步骤数量上说，连接一个已有仓库最多也就五六条命令，比装一个前端脚手架简单多了。但它涉及的东西横跨了本地文件系统、Git 配置、网络认证、远端权限四个层面，任何一层出问题，表现都是同一句“失败”。这就是它烦人的地方——错误信息一样，原因可能完全不同。

举个最常见的例子：Permission denied。可能是 SSH 密钥没生成，可能是密钥生成了但没加到平台账号里，可能是加进去了但本机ssh-agent没加载，可能是~/.ssh/config里给这个主机配了别的密钥文件，还可能是仓库路径写错了导致落到别的账号上。这五种原因报出来的第一行提示几乎一模一样，只靠那行红字根本判断不出来，得一层层往上验。

另外 VS Code 有一个特点：它会在你打开文件夹的瞬间扫描.git目录，如果当前文件夹不是仓库根目录、而是仓库的子目录，它也能识别，但识别的结果是“当前目录属于某个仓库”，这时候你在源代码管理面板里看到的更改列表是整个仓库的，很容易误操作到项目外的文件。我刚用的时候就被这个坑过，在src/目录下打开，以为只提交了自己改的那两个文件，结果把别人改的配置文件一起提交了。所以我的习惯是：永远在仓库根目录打开 VS Code，看到状态栏左下角显示分支名，才确认位置对了。

2. 前置环境：Git 装好、身份配好、凭证选对

这一步是最容易被跳过的，但它是后面所有操作的底座。我见过太多人克隆失败后反复重装 VS Code，其实问题在于 Git 根本没装，或者装了但 PATH 没配好，VS Code 检测不到。先花十分钟把这部分做扎实，后面会顺很多。

2.1 确认 Git 是否可用以及版本

打开 VS Code 的集成终端（快捷键是反引号那个键），敲一条最基础的命令：

git --version

能输出版本号就说明 Git 在 PATH 里。如果提示“不是内部或外部命令”或者“command not found”，那就是没装或者没进 PATH。Windows 上装的时候有一个选项叫“Adjusting your PATH environment”，默认选的是“Git from the command line and also from 3rd-party software”，保持默认就行；如果选成了“Use Git from Git Bash only”，那 VS Code 的默认终端（PowerShell 或 CMD）就找不到 git，得手动改终端类型或者重新装一遍。macOS 上一般敲git --version会触发命令行工具安装提示，跟着装完就好，不需要额外操作。Linux 发行版用包管理器装，装完顺手git --version验一下。

版本上我建议至少 2.23 以上，因为git switch和git restore这两个更语义化的命令是那个版本引入的。不是必须，但用起来比git checkout清楚得多——checkout一个命令干三件事（切分支、恢复文件、游离 HEAD），新手很容易误操作把没提交的改动覆盖掉。版本低也不用急着升级，checkout一样能用，只是要更小心。

VS Code 这边还要确认一件事：它有没有识别到 Git。打开命令面板（Ctrl+Shift+P 或 Cmd+Shift+P），输入Git: Show Git Output，如果输出里能看到版本信息和路径，说明打通了。如果这里是空的或者报错，去设置里搜git.path，手动填上 git 可执行文件的全路径，Windows 一般是C:\Program Files\Git\cmd\git.exe。这一步很多人不知道，遇到“VS Code 里 Git 图标不见了”的时候，八成就是这个原因。

2.2 用户身份和换行符，两个必须配的全局项

装完 Git 第一件事是配身份，这不是可选项。Git 每次提交都要记录作者名和邮箱，没配的话提交会直接失败，或者用系统默认值凑一个奇怪的名字上去，后面在提交历史里看着非常难受。

git config --global user.name "你的名字或代号" git config --global user.email "你的邮箱"

邮箱这里有个细节值得说：如果你希望提交历史里的邮箱和托管平台账号对应上，就用账号绑定的那个邮箱；有些平台提供了专门的匿名邮箱，用了之后提交不会暴露真实邮箱，但历史里的作者信息也会显示成那个匿名地址。团队协作场景下，我倾向于用真实可辨识的邮箱或统一的团队代号，方便出问题时定位是谁改的。用git config --global --list可以确认配置生效。

第二个必须配的是换行符处理。Windows 用 CRLF，Unix 系用 LF，同一个文件在两边来回倒腾，Git 会以为整个文件都改了，diff 里一片红一片绿，实际内容一个字没动。这个问题的根源是core.autocrlf没设对：

# Windows git config --global core.autocrlf true # macOS / Linux git config --global core.autocrlf input

true的含义是：提交时把 CRLF 转成 LF 存进仓库，检出时再把 LF 转回 CRLF，仓库里统一是 LF。input是提交时转成 LF，检出时不转换。这样仓库里始终是 LF，跨平台协作就不会因为换行符产生无意义的 diff。

注意：这个配置只对之后的操作生效，已经提交进仓库的 CRLF 文件不会自动修正。如果接手的是一个历史遗留仓库，里面已经混了两种换行符，别急着批量转换，那会产生一个巨大的 diff，review 的时候没人看得下去。正确做法是先跟团队确认规范，然后单独开一个提交专门做格式化，并且在这个提交的说明里写清楚“仅换行符变更，无逻辑改动”。

我一般在项目根目录再放一个.gitattributes文件，把文本文件的换行符策略写死，这样不管谁用什么系统、本地autocrlf配成什么样，行为都一致：

* text=auto *.sh text eol=lf *.bat text eol=crlf *.png binary *.jpg binary

这样做的价值在于“配置跟着仓库走”，而不是跟着每个人的机器走。团队里总有人懒得配全局项，靠仓库里的约定兜底最省心。

2.3 HTTPS 还是 SSH，选一个然后配到底

连接远端仓库有两条通道，用 HTTPS 地址还是 SSH 地址，这是第一个要做的选择。两者的差别不只是“要不要输密码”，还牵扯到凭证存储、端口限制、多账号管理等一堆事。

我的建议是：单账号、图省事，用 HTTPS；多账号、经常换仓库、或者长期做开发，用 SSH。SSH 配一次能用很久，而且~/.ssh/config可以给不同主机配不同密钥，多身份切换非常干净。HTTPS 的优势是上手快，遇到网络限制时也更容易通。

HTTPS 这边的关键点是：很多托管平台早就取消了账号密码直接认证，必须用访问令牌代替密码。令牌在平台的个人设置里生成，生成时要注意勾选权限范围，只读和读写的令牌是分开的，克隆公开仓库用只读就够，要推送就必须有写权限。令牌生成后只显示一次，务必当场复制存好，页面一关就再也看不到了，只能重新生成。

令牌不能每次都手输，得配凭证助手：

# Windows git config --global credential.helper manager # macOS git config --global credential.helper osxkeychain # Linux（临时缓存，单位秒，这里是一小时） git config --global credential.helper 'cache --timeout=3600'

Windows 的 manager 会把凭证存进系统凭据管理器，macOS 的 osxkeychain 存进钥匙串，这两者都是持久化的，配一次基本不用再管。Linux 的 cache 是内存缓存，重启就没了，也有把凭证明文存文件的store方式，但那个是明文，我不推荐在共用机器上用。

SSH 这边分三步。先生成密钥对，用 ed25519 算法，比老的 RSA 更短更安全：

ssh-keygen -t ed25519 -C "备注信息，一般写邮箱或用途"

一路回车用默认路径~/.ssh/id_ed25519就行。如果提示已有文件，说明之前生成过，别覆盖，要么用已有的，要么换个文件名。私钥文件权限必须是 600，权限太松 SSH 会拒绝使用，macOS 和 Linux 上执行chmod 600 ~/.ssh/id_ed25519即可。

然后把公钥（.pub结尾那个文件）的内容完整复制，粘贴到平台账号的 SSH 密钥设置页。这里最容易出错的是复制不全——公钥是一整行，中间不能有换行，粘贴时如果终端自动折行，很容易多复制一个换行符进去，导致验证失败。稳妥的做法是用命令直接输出到剪贴板：macOS 用pbcopy < ~/.ssh/id_ed25519.pub，Windows 用clip < 路径，Linux 用xclip -sel clip。

最后验证连通性：

ssh -T git@主机地址

第一次连接会问是否信任主机指纹，输yes。成功的话会返回一条欢迎信息，带你的用户名。如果返回Permission denied (publickey)，说明公钥没生效，检查顺序是：公钥内容是否完整、是否贴到了正确的账号、ssh-agent是否加载了私钥（ssh-add -l查看，没有就ssh-add ~/.ssh/id_ed25519）。

3. 方案一：把已有仓库克隆到本地

场景 A 是最常见的：同事发来一个仓库地址，说“你拉一下这个”。这件事的核心命令只有一条，但围绕它的细节不少。

3.1 克隆命令的完整流程和参数选择

最基础的克隆：

git clone <仓库地址>

执行后会在当前目录下建一个和仓库同名的文件夹，把代码和完整的提交历史都拉下来，同时自动把远端命名为origin，把默认分支设为本地当前分支，并且建立好追踪关系。也就是说，克隆完之后你直接git pull和git push都能用，不用再配任何东西——这就是我在 1.1 里说场景 A 最省事的原因。

但实际工作中经常需要加参数。几个我常用的：

# 指定本地文件夹名，避免和已有目录冲突 git clone <仓库地址> 项目目录名 # 只拉默认分支，仓库很大时能省不少时间 git clone --single-branch <仓库地址> # 浅克隆，只拉最近一次提交，适合只想看代码不想参与开发的场景 git clone --depth 1 <仓库地址> # 指定要拉的分支 git clone --branch 分支名 <仓库地址>

--depth 1这个参数值得单独说。有些仓库历史很长，动辄几百兆，克隆下来要等好几分钟。如果只是想跑起来看看效果、或者做临时代码审查，浅克隆能把这个时间压到几秒。代价是拿不到完整历史，git log只能看到一条，也不能基于历史做blame或者回溯旧版本。后面如果发现自己需要完整历史，可以补：

git fetch --unshallow

这个命令会把浅克隆补成完整克隆。我一般的工作流是：临时看代码用浅克隆，确认要长期参与开发了再补全，或者干脆删了重克隆，反正也不费事。

还有一个坑要说：克隆之前先确认自己在哪个目录。我见过不少人在桌面上敲克隆命令，结果项目文件夹散落在桌面，和一堆临时文件混在一起。更麻烦的是“嵌套克隆”——在一个已经是仓库的目录里再克隆一个，Git 允许这么做，但会导致内层仓库被外层仓库当成普通文件夹跟踪（或者反过来，取决于外层有没有配.gitignore），后面提交时莫名其妙带进去一堆文件。养成习惯，克隆前pwd看一眼，或者干脆先建一个统一放代码的目录，所有项目都克隆到那里面。

3.2 用 VS Code 图形界面克隆，比命令行省事吗

VS Code 提供了完整的图形化克隆流程，适合不想记命令的人。入口有两个：欢迎页上的“克隆 Git 仓库”，或者命令面板里的Git: Clone。

点下去之后会弹出一个输入框，让你填仓库地址。粘贴地址回车，它会再问你要存到哪个目录，选好之后开始克隆。克隆完成后右下角会弹一个提示，问“是否打开克隆的仓库”，点打开，VS Code 就会在新窗口里加载这个项目。整个过程不需要碰命令行。

这个流程的好处是省了“切目录、敲命令、再打开文件夹”这几步，一步到位。但它有个隐藏行为要注意：克隆结束后，VS Code 会把新克隆的仓库加入“最近打开”列表，但不会自动帮你切换工作区（取决于版本和设置）。如果你点了“添加为工作区文件夹”而不是“打开”，那这个仓库是作为一个子文件夹加进当前窗口的，当前窗口如果是另一个项目，就会出现两个仓库混在一个工作区里的情况。这时候源代码管理面板会显示两个分组，提交时很容易选错。

提示：如果你确实需要在一个窗口里同时管理多个仓库（比如前端和后端分开的两个仓库），用工作区文件（.code-workspace）是正确做法，每个文件夹独立显示。但如果你只是临时想打开一个仓库，就选“打开”，别选“添加为工作区文件夹”。

另外，图形化克隆在遇到认证失败时，提示信息比命令行更简略，只是弹一个“克隆失败，是否重试”。这时候点“输出”面板，切到 Git 通道，才能看到具体的错误信息。我遇到界面报错的第一反应永远是看输出面板，那里才有真正的原因。

3.3 克隆完之后，先做这四项检查

克隆成功不等于环境正常。我每次拉完新仓库，会按顺序做四件事，能提前发现大部分隐患。

第一，确认当前分支和远端是否一致。git status会显示类似“位于分支 main，与 origin/main 一致”。如果显示“领先”或者“落后”，说明克隆过程中有东西没同步。第二，确认远端地址对不对：git remote -v会列出 fetch 和 push 两个地址，正常情况下两者相同。如果 push 地址是空的或者指向别的地方，那后面推送必然失败。

第三，看一眼.gitignore有没有。如果没有，说明这个仓库可能没有规范地管理过，赶紧自己补一个，把node_modules、dist、.env、IDE 配置目录这些该忽略的写进去。我接手的仓库里，十个有三个.gitignore写得不完整，导致后面提交里混进编译产物，仓库体积越滚越大。

第四，跑一遍项目。这一步听起来像是废话，但很多人在连接仓库这件事上卡住，根源是代码本身就跑不起来，误以为是 Git 的问题。先把依赖装好、构建跑通，再动提交的事，心里有底。

4. 方案二：把本地已有代码接上远端仓库

这是最容易出问题的场景。典型情况是：你在本地写了一个项目，写了一段时间，现在想把它放到远端仓库里管理；或者远端已经建好了一个空仓库（带了一个初始 README），你要把本地代码推上去。两边都有内容，但历史各自独立。

4.1 初始化本地仓库并完成第一次提交

如果本地目录还不是 Git 仓库，先初始化：

cd 项目目录 git init

新版 Git 初始化出来的默认分支名可能是master，而远端仓库的默认分支多半是main。这个不一致会在后面推送时制造麻烦，所以初始化完先确认一下：

git branch

如果显示master而你想要main，直接重命名：

git branch -M main

顺便可以把全局默认分支也改掉，以后新建仓库都是main：

git config --global init.defaultBranch main

接下来把文件加入暂存区并提交。这里的关键是先看一眼会提交什么，别上来就git add .：

git status git add . git status

两次git status之间，你能清楚看到哪些文件被加入了。这一步非常重要，因为本地目录里通常混着一堆不该进仓库的东西：环境配置文件、编译产物、日志、.DS_Store、编辑器临时文件。一旦提交进去，后面即使删掉，历史里也还留着，尤其是包含密钥的配置文件，提交上去就相当于泄露了，只能整个历史重写，非常麻烦。

提交：

git commit -m "初始化项目，导入本地代码"

提交信息我建议写清楚这是什么，别写“first commit”或者“update”这种。历史记录是给未来的自己和同事看的，写明白能省掉很多沟通成本。

4.2 建立远端关联，git remote的几个常用操作

本地仓库有了提交，现在要告诉它“远端在哪”。命令是：

git remote add origin <仓库地址>

origin只是一个名字，是约定俗成的叫法，不是关键字。你可以叫upstream、source或者任何名字，只是后面所有命令里都得用这个名字。用origin的好处是所有教程和文档都这么写，不容易搞混。

关联完确认一下：

git remote -v

应该输出两行，fetch 和 push 各一个地址。如果只有一行或者地址不对，说明加错了。几种常见情况：

• 地址写错了，想改：git remote set-url origin <新地址>
• 想换个名字：git remote rename origin upstream
• 加错了想删：git remote remove origin
• 想同时关联多个远端（比如一个自己的 fork，一个上游主仓库）：再加一个不同名字的 remote 就行，拉取和推送时指定名字区分。

这里有个容易忽略的点：一个仓库可以关联多个远端，但git pull和git push在不指定名字时只用默认追踪的那个。如果你加了两个远端，记得用git remote -v确认哪个是origin，别推错了地方。我就干过一次，把内部测试代码推到了公开仓库的分支上，虽然立刻删了，但那个仓库的提交历史里留下了痕迹。

我有一次遇到fatal: remote origin already exists，是因为之前git init之后手滑加过一次远端。这时候不用慌，先用git remote -v看看现有的地址是什么，如果就是你要的，跳过这一步直接推送；如果是旧的，用set-url改掉，别用remove再加，多此一举。

4.3 第一次推送，以及为什么要加-u

本地有提交、远端已关联，接下来推送：

git push -u origin main

如果没有加-u，第一次推送会报错，提示“当前分支没有上游分支”。加了-u（也就是--set-upstream）之后，Git 会记住“本地 main 对应远端 origin 的 main”，以后直接git push和git pull就行，不需要再写后面那一串。

这个“追踪关系”是可以随时查和改的：

# 查看每个本地分支追踪的远端分支 git branch -vv # 给已有分支补设上游 git branch --set-upstream-to=origin/main main

VS Code 的状态栏左下角会显示当前分支名，如果分支名旁边有一个小云朵带箭头的图标，说明追踪关系已建立，点那个图标就是同步（先拉后推）。如果没有图标或者点了没反应，多半就是没设上游。这个细节很多人不知道，看到状态栏没有同步按钮就以为 VS Code 坏了，其实只是配置问题。

4.4 推不上去怎么办：两类高频冲突的处理

第一类：远端有本地没有的提交。典型表现是远端建仓库时勾选了“初始化 README”，而本地没有这个文件。推送时报错Updates were rejected because the remote contains work that you do not have locally。

解决思路是先把远端的东西拉下来合并，再推。因为两边历史不相干，直接git pull会报refusing to merge unrelated histories，要加参数：

git pull origin main --allow-unrelated-histories

这个参数的意思是“我知道这两条历史没关系，强行合”。执行后 Git 会尝试合并，如果有同名文件冲突（比如都有 README），会进入冲突状态，需要手动解决。VS Code 的合并编辑器在这里很好用，冲突文件会高亮，上面有“接受当前更改”“接受传入更改”“保留双方”几个按钮，点完保存，然后：

git add . git commit -m "合并远端初始提交" git push -u origin main

第二类：远端分支有别人的新提交，你本地也有新提交。这种是日常最常见的，推送被拒后不能硬推（--force会覆盖别人的提交，团队协作里绝对不能用）。正确做法是先拉取再推送：

git pull --rebase origin main

用--rebase而不是默认的 merge，好处是把你本地的提交“搬到”远端最新提交之后，历史是一条直线，不会产生一个无意义的合并提交。代价是如果有冲突，要在 rebase 过程中逐个解决，比 merge 稍微麻烦一点。新手可以先不用--rebase，用默认 merge 也能work，只是历史里会多出合并节点。

注意：git push --force在共享分支上是禁用操作。它会用你的本地历史直接覆盖远端，别人推上去的提交会凭空消失。真需要覆盖（比如推错了敏感信息要清理历史），用--force-with-lease，它会在覆盖前检查远端有没有你不知道的新提交，有就拒绝，安全得多。

5. VS Code 的 Git 面板，哪些能用哪些别碰

命令行会了之后，图形界面确实能提速不少。但 VS Code 的 Git 集成有一些“聪明过头”的设计，不理解它的行为逻辑，容易做出自己不想要的操作。

5.1 界面元素逐个拆解

左侧活动栏那个分叉的图标就是源代码管理视图。点开之后从上到下大致是几块：最上面是当前仓库名和分支名，中间是提交信息输入框，下面是“更改”“暂存的更改”两个分组，最底下可能还有“时间线”“Git 图表”之类的扩展入口。

“更改”分组里列的是工作区里被修改过但没暂存的文件。每个文件右边有个+号，点了就把这个文件加到“暂存的更改”里，相当于git add 文件名。文件左边如果有字母标记，M是修改，U是未跟踪（新文件），D是删除，R是重命名。点击文件名会打开 diff 视图，左边是改之前，右边是改之后，这个视图比命令行的 diff 直观太多，我大部分代码审查时间都花在这里。

提交信息输入框里写完信息，按 Ctrl+Enter（macOS 是 Cmd+Enter）就提交暂存区的内容。这里有个开关要特别注意：设置里的git.enableSmartCommit。打开之后，如果你没有暂存任何文件就提交，VS Code 会自动把所有更改都加进去再提交。这个功能对“改了一堆小东西想一次性提交”很方便，但对“只想提交其中两个文件”是灾难——你以为只是提交了暂存的，实际上全提交了。我的建议是把它关掉，手动暂存，多一步但心里有数。

5.2 提交、同步、拉取三个动作的区别

界面上最容易混的是这三个：提交（Commit）、同步（Sync Changes）、拉取（Pull）。

提交只是把暂存区的改动记录到本地仓库，不涉及网络。很多人以为点了提交就等于上传了，结果关掉电脑，代码只在本地，换台机器就没了。同步是“先拉后推”的组合动作，先执行git pull把远端的新提交拉下来，再执行git push把本地的推上去。如果拉取过程中有冲突，同步会中断，让你先解决冲突。拉取就是单纯的git pull。

我的习惯是分开做：先点拉取，看看有没有新东西、有没有冲突，确认没事再点推送。用“同步”一步到位看着快，但出问题时你不知道是拉取失败了还是推送失败了，排查起来多发一层懵。

还有一个常被误会的按钮：分支名旁边的圆形箭头是“刷新”，只是重新扫描工作区状态，不涉及网络。真正的远端状态要靠git.autofetch自动拉取，或者手动执行Git: Fetch。

5.3 几个值得改的设置项

打开设置搜索git，有几个值得调整。下面是我自己在用的配置，粘到settings.json里就能生效：

{ "git.autofetch": true, "git.autofetchPeriod": 180, "git.confirmSync": false, "git.enableSmartCommit": false, "git.postCommitCommand": "none", "git.openRepositoryInParentFolders": "always", "git.untrackedChanges": "separate", "files.eol": "\n" }

git.autofetch打开后，VS Code 会定期（默认三分钟，这里的autofetchPeriod单位是秒）去远端查有没有新提交，有的话在状态栏提示你落后了几个提交。这个功能很实用，能避免长时间基于过期代码开发。但仓库特别多、或者远端响应慢的时候会有点吵，可以调大间隔或者关掉。

git.openRepositoryInParentFolders设成always，意思是打开一个子目录时，自动往上找仓库根目录并加载。这个前面提过，好处是方便，坏处是容易在错误的层级操作，所以我还是建议养成从根目录打开的习惯，这个设置只是兜底。

git.untrackedChanges设成separate，会把未跟踪文件单独分组，不和已修改文件混在一起。这样一眼就能看出哪些是新文件，避免误提交。

files.eol设成\n，和前面core.autocrlf的配置配合，保证 VS Code 保存文件时用 LF，不乱加 CRLF。这一条对跨平台团队尤其重要，我之前带的项目里，Windows 同事每次保存都改换行符，diff 里全是噪音，加上这条之后清爽了。

6. 常见问题与排查速查表

前面讲的是“应该怎么做”，这一节讲“做错了怎么救”。下面这些是我这几年实际遇到过的，按症状整理成表，方便对照。

6.1 认证与权限类问题

认证问题排查有个通用思路：先在命令行里试，命令行通了再回 VS Code。因为 VS Code 会复用系统凭证，命令行里失败的东西在界面里一样失败，而命令行能看到完整报错信息。我排查这类问题的标准动作就是打开终端，手动敲一遍git fetch，看它到底说什么。

还有一个隐蔽情况：机器上配了多个账号，HTTPS 方式下凭证助手是按域名存的，同一个域名下只能存一套凭证，切换账号时必须先清掉旧的。Windows 上是“凭据管理器”里找到对应条目删掉，macOS 是“钥匙串访问”里搜出来删。SSH 方式下这个问题的解法更优雅，在~/.ssh/config里给不同账号配不同 Host 别名和密钥，克隆时用别名地址就行。

6.2 分支与历史类问题

游离 HEAD 这个状态新手最容易被吓到。它出现的原因通常是在 VS Code 里点了某个历史提交、或者 clone 之后 checkout 了某个 tag，此时 HEAD 不指向任何分支，你做的提交不属于任何分支，切走就找不回来了。VS Code 状态栏左下角会显示一串提交哈希而不是分支名，看到这个就要警觉。补救很简单，git switch -c 临时分支就把当前位置保存成一个新分支了。

index.lock也很常见。VS Code 的 Git 操作和终端里的 Git 操作同时进行，或者编辑器卡死强杀进程，都可能留下这个锁文件。清理前先确认没有 Git 进程在跑（ps aux | grep git或任务管理器里看），否则删了还会有。

6.3 文件与显示类问题

中文路径转义这条坑过我不止一次，尤其是接手国内团队的老项目，文件名全是中文，git status输出一屏幕的八进制转义，根本没法看。加上core.quotepath false之后就正常显示了，纯显示层的配置，不影响任何实际行为，可以放心加。

大小写那条要小心。macOS 和 Windows 的文件系统默认不区分大小写，所以把Button.js改成button.js，文件系统认为这是同一个文件，Git 也就认为没变化。要改的话得用两步走：

git mv Button.js button.js.tmp git mv button.js.tmp button.js

或者直接用git mv加--force。Linux 上没这个问题，但团队里只要有一个人用 macOS，这个文件推上去之后在 Linux 那边就可能引发引用路径找不到的错误，所以重命名文件时要格外注意。

7. 一些踩过坑之后的实际体会

关于“连接已有仓库”这件事，我最后想说的不是技术细节，而是一个习惯问题：动手前先git status和git remote -v各看一眼。这两条命令的输出加起来不超过十行，但能提前暴露九成的问题——当前在哪个分支、有没有未提交的改动、远端地址对不对、追踪关系建没建。我现在到一台新机器、接一个新仓库，第一件事就是这两条命令，比看任何文档都快。

另一个体会是，不要迷信图形界面。VS Code 的 Git 集成做得确实好，diff、合并、暂存这些操作比命令行直观太多，我日常八成的 Git 操作都在面板里完成。但它终究是命令的封装，遇到它处理不了的情况——比如历史需要重写、需要精细控制 rebase、需要同时操作多个远端——还是得回到终端。把命令行那几条基础命令练熟，图形界面用起来才有底气，出问题时也知道按钮背后发生了什么。

还有一个具体的小技巧：给常用的仓库地址做个本地索引。我在~/.ssh/config里给不同的代码主机配了简短的 Host 别名，克隆的时候地址能短一大截，输错概率也低很多：

Host work HostName 主机地址 User git IdentityFile ~/.ssh/id_ed25519_work Host personal HostName 主机地址 User git IdentityFile ~/.ssh/id_ed25519_personal

配好之后，克隆写成git clone work:组织/仓库.git就行，多账号也不会串。这个配置文件是纯文本，跟着自己的机器走，换电脑时复制过去就能用，比记一堆完整地址省事得多。