Git安装前的准备工作及避坑指南

一、安装前的准备工作

1. 检查系统环境

   • Windows：建议使用 Windows 10/11，64 位系统。
   • macOS：确保系统版本 ≥ 10.15（Catalina）。
   • Linux：推荐 Ubuntu 20.04+、Debian 10+ 或 CentOS 7+。

2. 卸载旧版本

   • 安装前删除旧版 Git：

bash

     # Linux/macOS
     sudo apt-get remove git  # Debian/Ubuntu
     sudo yum remove git      # CentOS

1. 网络环境
   • 国内用户建议配置代理或使用镜像源（如清华 TUNA、阿里云镜像）。

---

二、分平台安装步骤

Windows

1. 下载安装包

   • 访问 Git 官网 下载最新版。

2. 安装配置选项

   • 关键选项（务必勾选）：
     • Checkout Windows-style, commit Unix-style line endings：避免换行符冲突。
     • Use Git Bash as the default shell：启用 Bash 命令行。
     • Git LFS（Large File Storage）：如需管理大文件。
   • 避免勾选：
     • Use HTTPS transport helper：可能引发代理问题，建议手动配置。

3. 常见问题

   • 错误：git: command not found
     • 解决：安装时未勾选 Git Bash，需重新安装并勾选该选项。
   • 权限问题
     • 以管理员身份运行 Git Bash，或配置用户权限。

macOS

1. 通过 Homebrew 安装（推荐）

bash

   # 安装 Homebrew（若未安装）
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   
   # 安装 Git
   brew install git

1. 直接安装
   • 下载 Git 官方安装包 安装，推荐勾选 Git Bash。

Linux

1. Debian/Ubuntu

bash

   sudo apt update
   sudo apt install git

1. CentOS/RHEL

bash

   sudo yum install git

1. Arch Linux

bash

   sudo pacman -S git

---

三、安装后验证

bash

# 检查版本
git --version

# 测试连接
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
git clone https://github.com/example/repo.git  # 尝试克隆仓库

---

四、常见问题与解决方案

1. 命令行找不到 Git

• Windows：
  • 检查 PATH 环境变量是否包含 Git\bin（默认路径：C:\Program Files\Git\bin）。
  • 重启终端或电脑生效。
• Linux/macOS：
  • 重新安装 Git 或手动添加到 PATH：

bash

    echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
    source ~/.bashrc

2. SSH 连接失败

• 问题：Permission denied (publickey).
• 解决：
  1. 生成 SSH 密钥：

bash

     ssh-keygen -t ed25519 -C "[email protected]"

1. 添加密钥到 SSH Agent：

bash

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

1. 将公钥（~/.ssh/id_ed25519.pub）添加到 GitHub/GitLab 账户。

3. 与 IDE 集成失败

• VS Code：安装 Git 扩展，配置 settings.json：

json

  {
    "git.path": "/usr/bin/git"  // 指定 Git 路径
  }

4. 文件编码冲突

• 问题：提交时出现 LF will be replaced by CRLF。
• 解决：

bash

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

5. 代理配置

• HTTP/HTTPS 代理：

bash

  git config --global http.proxy http://your-proxy:port
  git config --global https.proxy https://your-proxy:port

• SSH 代理：

bash

  git config --global core.sshCommand "ssh -o ProxyCommand='ncat -x your-proxy:port %h %p'"

---

五、高级配置建议

1. 加速 Git 下载
   • 配置国内镜像源：

bash

     git config --global url."https://mirrors.tuna.tsinghua.edu.cn/git".insteadOf "https://github.com"

1. 自定义别名

bash

   git config --global alias.co checkout
   git config --global alias.st status

1. 多账号配置
   使用 git config --global user.name/email 或针对仓库配置：

bash

   git config user.name "Work Name"
   git config user.email "[email protected]"

---

六、终极验证

1. 克隆仓库测试

bash

   git clone https://github.com/git/git.git
   cd git
   git status  # 检查是否正常显示仓库状态

1. 推送测试

bash

   git commit -m "test"
   git push origin main  # 确保能成功推送

引用

---

七、常见错误代码

错误代码	可能原因	解决方案
fatal: unable to access...	网络问题	检查代理或更换镜像源
Permission denied (publickey)	SSH 密钥未配置	重新生成密钥并添加到 Git 服务端
error: failed to push some refs to...	本地与远程版本冲突	git pull 同步最新代码后再推送

---

通过以上步骤，您应该能顺利安装 Git 并避免常见问题。

一、Windows 系统避坑指南

1. 安装路径不要有中文或空格

• 坑点：路径如 C:\Program Files\Git 是安全的，但 C:\软件\Git 或 C:\My Tools\Git 可能导致权限问题或脚本异常。

• 解决：使用默认路径 C:\Program Files\Git。

2. 选择正确的默认编辑器

• 坑点：默认的 Vim 对新手不友好，误触可能导致界面卡死。

• 解决：安装时在 "Choosing Default Editor" 步骤选择 Nano 或 VSCode。

3. 换行符配置（CRLF vs LF）

• 坑点：Windows 和 Unix 系统换行符不同，可能导致提交后文件显示全部修改。

• 解决：安装时在 "Configuring Line Endings" 页面选择：

  • Checkout Windows-style, commit Unix-style（推荐）
    （git config --global core.autocrlf true）

4. 添加 Git 到系统环境变量

• 坑点：安装时未勾选添加环境变量，导致命令行无法识别 git 命令。

• 解决：安装时勾选 Git from the command line and also from 3rd-party software。

---

二、macOS 系统避坑指南

1. 不要重复安装命令行工具

• 坑点：通过 git 命令触发安装时，可能同时存在 Homebrew 和 Xcode 的 Git 版本。

• 解决：

  • 优先用 Homebrew：brew install git

  • 或官方下载安装包：Git for macOS

  • 检查路径：which git 应显示 /usr/local/bin/git（Homebrew）而非 /usr/bin/git（Xcode 自带）。

2. 解决 Xcode 依赖问题

• 坑点：首次使用 Git 时可能要求安装 Xcode 命令行工具（耗时较长）。

• 解决：提前手动安装：

  bash

  xcode-select --install

---

三、Linux 系统避坑指南

1. 使用包管理器安装

• 坑点：手动编译安装易缺失依赖项。

• 解决：

  bash

  # Debian/Ubuntu
  sudo apt update && sudo apt install git
  
  # CentOS/RHEL
  sudo yum install git

2. 更新旧版本 Git

• 坑点：系统仓库版本可能过旧（如 Ubuntu 18.04 默认 Git 2.17）。

• 解决（Ubuntu 示例）：

  bash

  sudo add-apt-repository ppa:git-core/ppa
  sudo apt update
  sudo apt install git

---

四、通用避坑要点

1. 首次配置用户信息

• 坑点：未设置用户名/邮箱导致提交失败（错误：Please tell me who you are）。

• 解决：

  bash

  git config --global user.name "Your Name"
  git config --global user.email "[email protected]"

2. SSL 证书问题（常见于企业网络）

• 坑点：fatal: unable to access 'https://...': SSL certificate problem

• 解决（临时关闭验证，非安全环境慎用）：

  bash

  git config --global http.sslVerify false

3. 代理配置

• 坑点：公司网络需代理才能访问远程仓库（如 GitHub）。

• 解决：

  bash

  # HTTP 代理
  git config --global http.proxy http://proxy.example.com:8080
  
  # 取消代理
  git config --global --unset http.proxy

---

五、安装后验证

1. 检查版本：

   bash

   git --version  # 应显示 ≥2.0

2. 检查配置：

   bash

   git config --list  # 确认 user.name/user.email 正确

---

十大避坑总结

1. ✅ 路径无中文/空格（Windows）

2. ✅ 换行符选 Commit Unix-style

3. ✅ 添加 Git 到环境变量

4. ✅ macOS 用 Homebrew 避免版本冲突

5. ✅ Linux 用包管理器安装

6. ✅ 首次安装后立即配置用户名/邮箱

7. ✅ 企业网络提前设置代理或关闭 SSL 验证

8. ✅ 默认编辑器选 Nano/VSCode（非 Vim）

9. ✅ 更新旧版 Git 到最新版

10. ✅ 安装后运行 git --version 验证

---

按此指南操作，可规避 99% 的安装问题！安装完成后建议运行 git config --global core.editor "code --wait" 将 VSCode 设为默认编辑器（需先安装 VSCode）。