企业官网建设流程全解析

不废话，直接开整。Git 这玩意儿，现在的开发者是真绕不开——写代码要版本管理，上 GitHub、Gitee 拉代码要认证，就连 VSCode 连远程服务器写代码，底层也大概率要跟 SSH 打交道。很多新手在 Windows 上装 Git，一路“下一步”点完就以为结束了，结果真到用的时候，要么提交代码报错，要么 SSH 连不上服务器，要么克隆仓库卡在认证环节。这篇文章就是把这些事从头到尾捋一遍：Git 怎么下载、怎么安装、安装完哪些配置必须做、SSH 密钥怎么生成怎么用，以及最常见的报错怎么排查。目标是让一个完全没接触过的小白，照着操作也能把整套环境跑通。

1. 动手之前，先搞懂 Git 和 SSH 到底解决什么问题

铺垫太多没意思，但有几个概念不提前说清楚，后面配置的时候大概率会"知其然不知其所以然"，出了问题也只会瞎试。

1.1 Git 不是网盘，它是"时间机器 + 多人协作工具"

很多人第一次接触 Git，把它当成 Dropbox、百度网盘一类的东西——以为就是把文件传到云端存起来。这个理解不能说全错，但会严重影响后面的使用体验。Git 的核心是版本快照：你每次提交（commit），它就把当前所有文件的状态打成一个快照，并且记录这次改动了什么、谁改的、什么时候改的。这样一来，你可以随时回退到任何一个历史版本，可以对比任意两次改动之间的差异，也可以拉出任意一条分支做实验，不满意直接丢弃。

工作区（Working Directory）、暂存区（Staging Area）、本地仓库（Local Repository）这三个概念，是理解 Git 操作的基础。工作区就是你电脑上看得见的文件夹；暂存区是提交前的中转站，决定哪些改动要进入下一条提交；本地仓库则是 Git 真正保存快照的地方。日常操作里，git add是把改动放进暂存区，git commit是把暂存区固化成本地仓库里的一个版本，git push才是把本地版本同步到远程仓库。

这套机制决定了 Git 是离线可用的：你不需要每次都连服务器才能提交版本，所有历史记录都在本地，远程服务器只是其中一个"交换中心"。这也是它和 SVN 这类集中式版本控制系统最本质的区别。

1.2 为什么非要配 SSH 密钥

Git 操作远程仓库（比如 GitHub、Gitee 或者公司内网的 GitLab），主流有两种认证方式：HTTPS 和 SSH。

HTTPS 的方式最直观——每次 push 或 pull 的时候输入账号密码。但问题也很明显：频繁输入很烦，而且很多平台已经不再支持纯密码认证，要求你用 Personal Access Token（个人访问令牌）代替密码。Token 是一长串随机字符，又不好记，输错了还得重新生成，体验相当糟糕。

SSH 的方式则是"一次配置，永久免密"。它基于非对称加密：你生成一对密钥，一把私钥（private key）留在自己电脑上，一把公钥（public key）上传到服务器。服务器用公钥加密一段随机信息，你的电脑用私钥解密，能解开就证明"你确实是你"。私钥不出本地，公钥随便分发，安全性比密码高得多，也方便得多。

所以你会发现，几乎所有开发者教程里，配置完 Git 的第一件事就是配 SSH 密钥。这是打通 Git 和远程仓库的"最后一公里"。

2. 下载与安装：官网、版本选择、安装选项逐项解释

Git 在 Windows 上的"官方默认实现"是Git for Windows，它附带了一个完整的模拟环境，让你能在 Windows 上使用几乎所有的 Git 命令。注意，这不等于"Git 只能在 Windows 上这么装"，只是对于绝大多数 Windows 用户来说，这就是最标准、最省心的答案。

2.1 下载渠道和版本选择

下载地址直接去 Git 官方网站（git-scm.com），点击首页的 Downloads 按钮，页面会自动识别 Windows 系统并给出 64-bit 版本的下载链接。如果自动识别不对，可以手动点击 "Windows" 进入下载页，选择对应的版本即可。

这里有个细节值得留意：官网提供两种安装包形态，一种是普通的 Setup .exe 安装包，另一种是 Portable 免安装版。我建议普通用户直接选 Setup 版，因为它会写入 Windows 的系统环境变量，还能在右键菜单里加上 "Git Bash Here" 和 "Open GUI Here" 两个入口，用起来非常顺手。Portable 版适合想完全绿色化、不往系统里写东西的场景，但配置起来徒增麻烦，新手不推荐。

版本选择方面，官网通常会提供 32-bit 和 64-bit 两个版本，现在的电脑基本都是 64 位，选 64-bit 即可。另外还有一个区分点是"最新版"和"维护版"，非特殊需求一律用最新版。Git 的版本迭代不太会引入破坏性变更，没必要像某些软件一样刻意停留在旧版本。如果你在公司内网或离线环境安装，需要提前下载好安装包；如果官网访问缓慢，可以尝试国内的一些院校镜像或开源镜像站下载，但要记得核对文件哈希（sha256），防止下载到被篡改的安装包。

2.2 安装向导里的每个选项都代表什么

Git for Windows 的安装界面虽然看起来是一路 "Next"，但中间有几个页面其实很关键，选错了后面会踩很多坑。我挑几个重点选项说一下。

选择组件（Select Components）页面，默认选项基本够用，但建议确保这几项是勾选的：

• Git Bash Here：在文件夹右键菜单中加入 Git Bash 入口。这是 Windows 下使用 Git 最顺手的终端，强烈建议保留。
• Git GUI Here：右键菜单里加入图形界面入口。虽然大多数人用命令行，但应急查看历史记录还是挺方便的。
• Associate .gitconfiguration files with the default text editor*：把 .git 开头的配置文件（比如 .gitignore、.gitattributes）与文本编辑器关联，双击就能打开编辑，方便。
• Check daily for Git for Windows updates：定期检查更新，可以开着，不影响日常使用。

还有一项 "Enable symbolic links"（启用符号链接），圆括号里写着 "requires the SeCreateSymbolicLink permission"。这个选项不是必需的，而且开启后会遇到权限问题，建议保持默认不勾选。

选择默认编辑器（Choosing the default editor used by Git）页面，默认选项是 Vim。如果你对 Vim 不熟悉，强烈建议在这里选择 "Use Visual Studio Code as Git's default editor"（前提是你已经安装过 VSCode），或者选 "Use Notepad++"。否则提交的时候不小心进到 Vim 界面，你会觉得 Git 卡死了，其实是一堆人不知道按i进入编辑模式、按Esc再输入:wq保存退出，硬生生把自己卡在 Vim 里，气得直接关终端。

调整 PATH 环境变量（Adjusting your PATH environment）页面，三个选项：

• Use Git from Git Bash only：只在 Git Bash 里能用 Git 命令，Windows 自带的 CMD/PowerShell 里用不了。
• Git from the command line and also from 3rd-party software：把 Git 加入系统 PATH，CMD、PowerShell、VSCode 终端里都能直接用git命令。这是最推荐的选择，也是默认选择。
• Use Git and optional Unix tools from the Command Prompt：把 Git 附带的 Unix 工具也加入 PATH，比如bash、sh、cat等。不建议选这个，因为会和 Windows 自带的同名命令冲突，造成一些莫名其妙的问题。

选择 HTTPS 传输后端（Choosing the HTTPS transport backend）页面，默认选项是 "Use the OpenSSL library"。这个保持默认即可。另一个选项是 Windows 自带的证书库，很少被用到，而且经常因为企业内网证书问题导致 SSL 报错。

配置换行符转换（Configuring the line ending conversions）页面，这是新手最容易踩坑的地方之一，我单开一节详细说。安装时默认选第一个 "Checkout Windows-style, commit Unix-style line endings" 就行，但这只是默认值，真正决定行为的是安装后git config core.autocrlf的设置，后面细讲。

2.3 装完后先验证一下

安装完成后，按下Win + R，输入cmd回车打开命令提示符，或者直接打开 PowerShell，输入：

git --version

能输出类似git version 2.47.1.windows.1这样的结果，说明安装成功且 PATH 配置正确。

再输入：

git config --list --show-origin

这条命令会列出 Git 当前生效的所有配置项，以及每条配置的来源文件路径。如果这里能正常输出，说明 Git 的核心已经跑通了。

顺手再检查一个细节：在任意文件夹空白处点右键，菜单里应该能看到 "Open Git Bash Here" 和 "Open Git GUI Here" 两个选项。如果没有，大概率是安装时把组件勾选去掉了，回头重新运行安装包，选择 "Modify" 补装即可。

3. Git 环境配置：用户名、换行符、编辑器一个都不能少

安装完成只是第一步，接下来这几项配置是"必做项"。不做的后果一开始可能看不出来，等到第一次 push 代码到远程仓库，就会发现提交记录里的作者信息是一串乱码一样的默认值，或者打开仓库看到满屏的红色告警。

3.1 设置提交身份（user.name 和 user.email）

Git 的每次提交都会记录作者信息，这个信息不是从系统自动读取的，而是纯靠user.name和user.email两个配置项。如果在提交之前没设置，Git 会强行弹出一个编辑器让你补填，很多人就是在这里卡住的。

打开终端，执行：

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

注意几个细节：

• --global表示全局生效，作用于当前 Windows 用户的所有仓库。如果你不想要全局配置，想每个仓库单独设置，可以去掉--global，进入对应仓库目录后再执行一次。
• 邮箱不一定要用注册 GitHub 的邮箱，但建议用同一个，这样提交记录能正确关联到你的平台账号。GitHub 后来也允许设置 noreply 邮箱来隐藏真实邮箱，但那是后话。
• 配置完之后，可以用git config --global --list确认一下是否写对。

这套配置的优先级是：系统级（system）< 全局级（global）< 仓库级（local），后写的覆盖先写的。当你遇到"我明明设置了用户名，怎么提交记录还是显示别人"这种诡异问题时，十有八九是某个仓库里有更高优先级的 local 配置把全局配置盖掉了。

3.2 换行符是新手最大的暗坑

Windows 和 Unix/Linux 系系统对文本文件的换行符处理不一样：Windows 用CRLF（回车 + 换行），Linux/macOS 用LF（仅换行）。Git 默认在 Windows 上检出（checkout）代码时把换行符转成CRLF，提交（commit）时再转回LF，这就是安装时那个默认选项的意思。

这个设计的初衷是好的：让 Windows 用户打开文件不出现奇怪的^M符号，同时保证仓库里存的是统一的LF。但问题来了，如果一个文件本来在仓库里是LF，你在 Windows 上修改后用CRLF提交，Git 会认为整个文件的每一行都变了——因为每一行的行尾都不一样了。结果就是git diff显示整个文件被改动，review 代码的人想骂人，合代码的人也容易一脸懵。

处理方式分几步：

1. 确认 autocrlf 状态。执行git config core.autocrlf，在 Windows 上默认是true。如果想看全局配置，用git config --global core.autocrlf。
2. 决定策略。如果你的项目只在 Windows 上开发，所有同事都是 Windows 用户，直接策略是设置git config --global core.autocrlf false，让 Git 不做任何转换，仓库里是什么样就什么样。如果你的项目要跨平台协作（比如有人用 macOS/Linux），更推荐在仓库根目录添加一个.gitattributes文件，显式指定哪些文件用什么行尾。例如：

* text=auto *.js text eol=lf *.py text eol=lf *.bat text eol=crlf

.gitattributes写清楚之后，Git 会严格按照文件规则处理，不再依赖每台机器上的core.autocrlf设置，这才是跨平台协作的正解。

3. 修复已有仓库。如果你已经不小心把CRLF提交进仓库了，可以执行：

git add --renormalize . git commit -m "Normalize line endings"

这个命令会根据当前.gitattributes或core.autocrlf规则，把仓库里所有文件的换行符重新规范一遍，生成一条专门的提交记录。之后大家的基线就统一了。

3.3 默认编辑器、大小写敏感与常用别名

换行符弄完，还有几个零零散散但实际很常用的配置。

默认编辑器。如果你安装 Git 时选的不是 VSCode，后面想改，可以用：

git config --global core.editor "code --wait"

前提是 VSCode 已经加入系统 PATH 才认code命令。设完之后，每次需要 Git 弹出编辑器写提交信息（比如git commit不带-m时），都会自动打开 VSCode 让你写，写完关掉标签页就算确认提交。

文件大小写敏感。Windows 文件系统默认大小写不敏感，但 Git 是大小写敏感的。这意味着你把Readme.md改成README.md，Git 可能不会自动识别这是一次重命名。正确做法是分两步：

git mv Readme.md README.md

或者强制改：

git config core.ignorecase false

不过这个配置改起来容易引起其他问题，建议只在需要重命名文件时用git mv手动处理，不要把ignorecase全局改成false。

常用别名。Git 支持给命令设置别名，减少重复输入。比如：

git config --global alias.st status git config --global alias.co checkout git config --global alias.cm "commit -m" git config --global alias.lg "log --oneline --graph --all --decorate"

配完后git st等于git status，git lg能输出一棵漂亮的提交历史树，日常用起来体验提升非常明显。

4. SSH 密钥从生成到验证：一步步打通免密登录

配置到这里，Git 本身已经能用了，但和远程仓库的交互还没打通。接下来就是整个教程的重头戏：SSH 密钥的生成与配置。这一步做完，git clone、git push、git pull这些操作就不再需要每次输入用户名密码或 Token 了。

4.1 生成密钥前先想清楚的两个问题

第一，用哪种算法？目前推荐用 Ed25519。它的密钥更短、生成更快、安全性也足够，而且是 OpenSSH 从版本 6.5 开始就支持的算法。GitHub、Gitee 这些主流平台都支持它。如果你需要兼容非常老旧的服务器（比如还在用 OpenSSH 6.4 以下版本的系统），才考虑用 RSA。RSA 密钥生成时建议把位数设为 4096：

ssh-keygen -t rsa -b 4096 -C "你的邮箱或备注"

第二，密钥放在哪里、叫什么名字？默认存放路径是C:\Users\你的用户名\.ssh\id_ed25519（或id_rsa）。如果你只有一台电脑、一个常用平台账号，直接用默认路径和默认文件名就行，可以少踩很多配置文件相关的坑。如果你有多个平台的多个账号，需要给不同密钥起不同的名字，比如github_work、gitee_personal、company_server，这部分我在第 5 节详细讲。

4.2 正式生成：算法、注释、密码短语

打开Git Bash（务必用 Git Bash，不要用 CMD 或 PowerShell，因为后面会用到一些 Unix 命令），执行：

ssh-keygen -t ed25519 -C "你的邮箱或备注"

敲回车后，系统会问你要把密钥保存在哪个文件：

Generating public/private ed25519 key pair. Enter file in which to save the key (/c/Users/你的用户名/.ssh/id_ed25519):

直接回车使用默认路径即可。

接着会问你是否设置 passphrase（密码短语）：

Enter passphrase (empty for no passphrase):

这里有两个选择：

• 直接回车留空：免密使用，私钥一旦泄露，别人就能直接使用它。但对个人本地电脑来说，方便性优先。
• 设置一个 passphrase：每次使用私钥时都要输入一次。如果配合 ssh-agent 使用，只需要在会话开始时输入一次，之后都不用重复输。

我更推荐的组合是：设置一个 passphrase，然后启用 ssh-agent 记住解锁状态。这样既安全又不用反复输入。关于 ssh-agent 的启用，见 4.4 节。

生成完成后，.ssh目录下会出现两个文件：

• id_ed25519：私钥，绝对不能泄露，谁拿到它谁就能冒充你。
• id_ed25519.pub：公钥，可以安全地提交给服务器或托管平台。

查看公钥内容，用：

cat ~/.ssh/id_ed25519.pub

输出是一行以ssh-ed25519 AAAA...开头的字符串，这就是待会要添加到平台的内容。

4.3 把公钥交给 GitHub / Gitee

公钥生成的下一步，是把公钥内容添加到你要用的代码托管平台。不同平台入口大同小异，这里以 GitHub 为例：

1. 登录 GitHub，点击右上角头像 → Settings。
2. 左侧菜单找到SSH and GPG keys。
3. 点击New SSH key按钮。
4. Title 随便填一个能区分用途的名字，比如 "My Windows PC" 或 "Home Desktop"。
5. Key type 保持默认的Authentication Key。
6. 把.pub文件里的内容完整复制，粘贴到 Key 输入框里。注意整段都要复制，不要加空格、不要换行、不要少字符。
7. 点击Add SSH key确认。

Gitee（码云）的路径类似：设置 → SSH 公钥 → 添加公钥。GitLab 也差不多：Preferences → SSH Keys。公司自建的 GitLab 通常是经过管理员限制的，如果上传公钥的地方找不到，找管理员要入口即可。

4.4 测试连接与 ssh-agent

公钥添加完成后，在 Git Bash 里测试一下：

ssh -T git@github.com

如果看到：

Hi 你的用户名! You've successfully authenticated, but GitHub does not provide shell access.

说明密钥认证成功，SSH 通道已经打通了。如果是 Gitee，命令是ssh -T git@gitee.com，成功提示类似。

这里有个小知识点：SSH 默认的端口是 22。如果你的网络环境里 22 端口不通（企业防火墙、校园网之类），可以改用 443 端口连接 GitHub，需要修改~/.ssh/config文件，这部分放到第 5 节一起说，因为和 config 文件的写法强相关。

ssh-agent 是干什么的？简单说，它是一个在后台运行的小程序，负责保存你解锁过的私钥，让其他 SSH 连接直接复用，不用反复输入 passphrase。Windows 自带的 OpenSSH 服务可以作为 ssh-agent 使用，但 Git for Windows 也有自己的 agent 实现。

为了让它更好用，建议在 Git Bash 里执行：

eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_ed25519

首次执行ssh-add时输入私钥 passphrase，之后在当前的 Git Bash 会话里，所有 SSH 连接都不需要再输入 passphrase。

不想每次打开 Git Bash 都手动执行eval "$(ssh-agent -s)"的，可以直接在 Windows 的"服务"（services.msc）里找到OpenSSH Authentication Agent，把启动类型改成"自动"，然后启动它。再把ssh-add ~/.ssh/id_ed25519加到你常用的 shell 启动脚本里，比如~/.bashrc或~/.profile。这样每次打开终端，agent 自动运行、秘钥自动加载，体验最流畅。

5. 多账号场景：一台电脑同时管理 GitHub、Gitee、公司服务器的密钥配置

很多人实际使用中会碰到这种情况：一个 GitHub 个人账号，一个 Gitee 账号（因为国内访问快，或者公司项目在上面），还有一台公司的 GitLab 服务器。这些平台上的账号邮箱都不一样，如果你还沿用默认的id_ed25519一个密钥走天下，服务器那边肯定会有冲突。单看某个平台没问题，但多个平台各传一次同一个公钥，一旦某个平台那边出了状况，或者你想撤销某个平台的访问权限，就得把所有平台全部重来一遍。更好的做法是分平台生成不同的密钥，然后通过~/.ssh/config文件告诉 SSH 客户端"哪个域名用哪把密钥"。

5.1 什么时候需要多密钥

我总结一下，出现下面任一情况，就说明你需要考虑多密钥方案了：

• 你在两个不同的代码托管平台都有账号，且邮箱不同。比如 GitHub 用私人邮箱，公司 GitLab 用公司邮箱。
• 你对不同项目希望使用不同的提交身份。比如个人开源项目和公司商业项目要严格区分。
• 你的公司安全策略要求每个系统使用独立密钥，或者要求定期轮换密钥，共用一把私钥会觉得很不稳妥。

5.2 config 文件的写法与含义

多密钥的核心是一个配置文件：~/.ssh/config。这个文件默认不存在，需要手动创建。在 Git Bash 里执行：

touch ~/.ssh/config

然后打开编辑（推荐用 VSCode 或 Notepad++）：

code ~/.ssh/config

写入如下格式的内容：

# GitHub Host github.com HostName github.com User git IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes # Gitee Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/id_ed25519_gitee IdentitiesOnly yes # 公司 GitLab Host gitlab.company.com HostName gitlab.company.com User git IdentityFile ~/.ssh/id_ed25519_company IdentitiesOnly yes

这里解释一下几个关键字段：

• Host：你在 SSH 命令和 Git remote 地址里使用的别名。它可以和真实域名一样（如github.com），也可以设置成自定义短名（如gh）。如果设置了自定义短名，远程仓库地址要相应修改，比如git@gh:用户名/仓库名.git。
• HostName：真实的服务器地址。
• User：SSH 登录用户名。对 GitHub/Gitee/GitLab 这些平台来说，固定是git，不用改。
• IdentityFile：指定使用哪个私钥文件。
• IdentitiesOnly yes：强制 SSH 只使用这里指定的私钥，不要尝试~/.ssh/id_ed25519或其他默认密钥。不加这一项，SSH 会先把默认密钥全部试一遍，如果数量多，认证会变慢，还可能出现"尝试了错误的密钥导致被服务器拒绝"这种隐性问题。

在这之前，你还需要为不同平台生成不同命名的密钥。比如：

ssh-keygen -t ed25519 -C "github_email@example.com" -f ~/.ssh/id_ed25519_github ssh-keygen -t ed25519 -C "gitee_email@example.com" -f ~/.ssh/id_ed25519_gitee

-f参数用于指定保存路径和文件名。生成之后，把对应.pub内容分别添加到对应平台即可。

配置完成后，测试一下：

ssh -T git@github.com ssh -T git@gitee.com

正常情况下，两条命令会分别显示你添加对应公钥时关联的用户名。每条连接都会按config文件里的 Host 精确匹配，使用对应的私钥。

如果遇到config文件不生效的情况，先检查文件权限。Windows 的 OpenSSH 对 config 文件权限有严格的要求，过宽的权限可能导致它被忽略。在 Git Bash 里可以执行：

ls -l ~/.ssh/config

如果文件权限太开放（比如 Everyone 有读权限），可以在文件属性的安全设置里收紧权限，只保留当前用户的读写权限。Git Bash 里也可以直接用chmod 600 ~/.ssh/config试试，某些场景下有效。

还有一个进阶需求：连接 GitHub 时通过走 443 端口而不是默认的 22 端口。格式是：

Host github.com HostName ssh.github.com Port 443 User git IdentityFile ~/.ssh/id_ed25519_github IdentitiesOnly yes

注意这里的 HostName 变成了ssh.github.com，端口是 443。之后git clone git@github.com:用户/仓库.git这种地址不需要改，SSH 会依据 Host 匹配到这段配置。

5.3 仓库地址和 remote 怎么改

SSH 配置完成之后，你之前用 HTTPS 方式克隆的仓库，remote 地址仍停留在https://github.com/xxx/xxx.git形式，不会自动切换。要么改用 SSH 地址重新克隆，要么手动修改现有仓库的 remote：

git remote set-url origin git@github.com:用户名/仓库名.git

或者直接编辑.git/config文件，把url =那一行替换成 SSH 格式。

判断当前仓库用的是哪个协议，用：

git remote -v

输出里https://开头就是 HTTPS 协议，git@开头则是 SSH 协议。多账号场景下，尤其要注意 remote 地址里的 Host 是否和config文件里定义的 Host 保持一致，否则匹配不上私钥，会一直报 Permission denied。

5.4 多账号踩坑记录

配置多账号的时候，我踩过几个坑，写出来给大家提个醒。

第一个坑是公钥上传到了错误的平台。A 平台的公钥文件复制到了 B 平台的设置页面上，看起来都是类似ssh-ed25519 AAAA...的格式，不仔细看根本分辨不出来。而且保存后平台也不会校验"这公钥是否已经其他平台在用"，所以经常出现"公钥添加成功了但认证总失败"的情况。解决方法是：在.pub文件的末尾会有你生成时填写的-C注释（邮箱或备注），对照一下平台上的收录记录，或者直接重新生成并重新上传。

第二个坑是本地存在多个 key 时，SSH 使用了错误的那个。SSH 的密钥选择逻辑是先看config文件，再看默认路径。如果你没有写config，或者写了但IdentitiesOnly没有加，SSH 可能会先把默认的id_ed25519（如果存在）发给服务器，服务器说"不识别这个 key"，它才尝试下一个。如果服务器有连接失败次数限制，试两三次就被封 IP 或者要求等一会儿了。这也是为什么我反复强调IdentitiesOnly yes一定要写。

第三个坑是passphrase 忘记了。私钥本身设置了 passphrase，但一旦忘记，没有任何找回手段，只能重新生成密钥、重新上传公钥、重新配置远程仓库。相比之下，公钥可以随便公开，重新生成之后旧公钥作废即可。所以设置 passphrase 前建议自己评估一下安全性收益和丢失成本，设置完之后可以用密码管理器存好。

6. 高频命令与疑难报错排查速查

环境配置讲得差不多了，最后这部分是"查字典"环节。我按实际使用频率整理了一份命令速查表和一份报错排查清单，遇到问题直接翻到这里对照。

6.1 日常开发高频命令一张表

这些命令没要求大家背下来，但建议在理解原理的基础上多用几次。比如git add到git commit到git push这条链路，其实对应的是"工作区 → 暂存区 → 本地仓库 → 远程仓库"四个层级的流转。概念立得住，命令就不会乱。

6.2 高频报错：Permission denied（publickey）怎么查

遇到最多的报错就是类似：

git@github.com: Permission denied (publickey). fatal: Could not read from remote repository.

很多人第一反应是"是不是我密码错了？"其实不是，这个报错说明 SSH 密钥认证环节失败了。按这个顺序排查：

1. 先确认 ssh-agent 里有没有加载正确的私钥。执行ssh-add -l，如果有输出，看是否包含你预期的那把 key 的指纹。没有的话执行ssh-add ~/.ssh/对应私钥文件。
2. 确认config文件是否匹配到了正确的 Host 和 IdentityFile。可以加-v参数看详细日志：ssh -vT git@github.com，日志里会输出尝试了哪些私钥文件。
3. 确认公钥是否确实添加到了平台。打开平台设置页，和本地.pub文件逐字符核对。
4. 如果用的是公司 GitLab，有时候是账号被禁用或未审核，联系管理员确认。

一个非常隐蔽的坑是：Windows 上如果同时装了 Git for Windows 和 Windows 自带的 OpenSSH，ssh命令可能指向了不同的实现，导致读到的~/.ssh路径不一样。Git for Windows 的 HOME 通常是C:\Users\用户名，但有些工具会把 HOME 指到别处。排查方式是在 Git Bash 里执行echo $HOME，看看路径是否如预期。

6.3 其他三个高频坑：换行、合并、分支名

报错一：LF will be replaced by CRLF

这个告警不是错误，不会阻断操作。它只是告诉你 Git 正在按照 autocrlf 规则转换换行符。如果这个提示反复出现且影响 diff 阅读，回到 3.2 节，把.gitattributes配置起来，一劳永逸。

报错二：fatal: refusing to merge unrelated histories

这个报错常见于两个仓库没有共同的历史基础，比如你在 GitHub 上新建了一个仓库但初始化了 README，本地又init了一个仓库，两边历史互不相干，直接pull就会报这个错。解决办法是显式允许不相关历史合并：

git pull origin main --allow-unrelated-histories

但要注意：这个操作会把两个完全不同历史合并到一起，之后可能产生大量冲突，建议先想清楚是不是有更合理的流程，比如直接重新克隆。

报错三：src refspec main does not match any

这个报错通常说明你还没有创建本地提交，或者当前分支名不是main，但推送时指定了main。解决办法是先写一个提交，或者看下当前分支名再推送：

git branch -M main git push -u origin main

git branch -M main是把当前分支重命名为main，如果你本地确实叫master，也可以用这条命令统一命名。

另外还有一个经常出现的提醒：fatal: could not read Username for 'https://github.com'。这个报错几乎可以断定是用 HTTPS 协议访问远程仓库时，没有正确配置凭据或者凭据过期了。最简单的解决方式是把 remote 地址改成 SSH 格式，参考 5.3 节。如果你确实想继续用 HTTPS，可以在 Windows 凭据管理器（Credential Manager）里找到旧的凭据删掉，下次 push 时重新输入账号密码或 Token。

个人经验到最后说一句：Git 和 SSH 这套东西，刚开始接触会觉得概念多、命令杂、配置文件又长，但真正常用的其实就那么几条命令加一个配置文件。与其把文档从头到尾背一遍，不如把本文提到的配置流程完整走一遍，然后找个真实的项目练手，克隆、修改、提交、推送、分支合并各来一轮。踩过两三个坑之后，你会发现自己对这些"玄学问题"基本都能独立定位了。如果后续碰到更刁钻的场景，比如 Windows 上 Git 命令在 PowerShell 里的兼容问题、大规模仓库的稀疏检出（sparse checkout）、或者 Git LFS 大文件存储，也可以顺着今天搭好的环境继续往下探索。先把地基打稳，剩下的都好说。