Git 安装与基础配置全攻略：用户名、SSH、换行符与常见报错排查

适用场景与准备

如果你需要拉取/提交代码、使用 GitHub/Gitee，或者要在 VS Code/IDE 里做版本管理，建议先把 Git 与 SSH 一次配置到位。本文按“装好 → 配好 → 验证 → 排错”的顺序来，照做即可。

你需要：管理员权限（Windows）或可安装软件权限（macOS）；一个代码托管账号（可选）。

Windows 安装：Git for Windows（推荐）

1）打开浏览器搜索“Git for Windows”，进入官方页面下载稳定版安装包。

2）安装过程中关键选项建议：

- PATH：建议选择让命令行与第三方软件都能使用 Git（安装器里通常叫“Git from the command line and also from 3rd-party software”）。

- 换行符：推荐“Checkout Windows-style, commit Unix-style”（兼顾团队协作）。

3）安装完成后打开 PowerShell 或 Git Bash，执行：

git --version

能看到版本号说明安装成功。

macOS 安装：两种常用方式

方式A（最省事）：终端执行：

xcode-select --install

安装后用 git --version 验证。

方式B（更可控）：安装 Homebrew 后执行：

brew install git

必做基础配置：用户名、邮箱、默认分支、换行符

把姓名与邮箱替换成你自己的：

git config --global user.name "Your Name" git config --global user.email "you@example.com"

推荐设置默认分支名为 main：

git config --global init.defaultBranch main

Windows 常见问题是换行符，建议明确设置（按团队约定为准）：

git config --global core.autocrlf true

检查配置：

git config --global --list

配置 SSH：免输入密码推送（推荐）

1）生成密钥（一路回车即可；想更安全可设置口令）：

ssh-keygen -t ed25519 -C "you@example.com"

2）加入 ssh-agent：

ssh-agent -s ssh-add ~/.ssh/id_ed25519

3）复制公钥（通常在 ~/.ssh/id_ed25519.pub），粘贴到代码托管平台的 SSH Keys 设置中。

4）验证连接（以 GitHub 为例）：

ssh -T git@github.com

常见报错排查（按出现频率排序）

1）git 不是内部或外部命令：未加入 PATH 或未安装成功。解决：重装 Git for Windows 并勾选让命令行可用；或重启终端/电脑。

2）Permission denied (publickey)：公钥未添加到平台/加载了错误的 key。解决：确认平台已添加公钥；执行 ssh-add -l 查看是否已加载；必要时重新 ssh-add。

3）LF/CRLF 警告：换行符设置与仓库规则不一致。解决：先和团队确认规则，再设置 core.autocrlf；有 .gitattributes 时以仓库规则为准。

4）中文路径/文件名显示异常：可尝试 git config --global core.quotepath false；同时尽量避免超长路径。

1分钟自检清单

- git --version 有版本号

- git config --global --list 看得到 user.name / user.email

- ssh -T 能通过平台认证（可选）

做到以上三点，你的 Git 环境就基本稳定了。