Git 配置指南

Git 相关的配置和工具使用文档。

基础配置

配置用户名和邮箱

Git 需要配置用户名和邮箱，用于提交记录。

查看当前配置

# 查看全局配置
git config --global user.name
git config --global user.email

# 查看所有配置
git config --global --list

设置全局用户名和邮箱

# 设置用户名
git config --global user.name "Your Name"

# 设置邮箱
git config --global user.email "your.email@example.com"

为特定仓库设置不同的用户名和邮箱

# 进入项目目录
cd /path/to/project

# 设置仓库级别的用户名和邮箱（不加 --global）
git config user.name "Your Work Name"
git config user.email "your.work@company.com"

# 查看当前仓库配置
git config --local user.name
git config --local user.email

SSH 密钥配置

SSH 密钥用于免密码与 Git 服务器进行安全通信。

检查现有 SSH 密钥

# 查看已有的 SSH 密钥
ls -al ~/.ssh

# 常见的密钥文件名：
# id_rsa / id_rsa.pub
# id_ed25519 / id_ed25519.pub

生成新的 SSH 密钥

生成 RSA 密钥（传统方式）

# 生成 4096 位 RSA 密钥
ssh-keygen -t rsa -b 4096 -C "your.email@example.com"

# 按提示操作：
# 1. 保存位置（默认 ~/.ssh/id_rsa）
# 2. 输入密码短语（可选，直接回车跳过）
# 3. 确认密码短语

生成 Ed25519 密钥（推荐）

# 生成 Ed25519 密钥（更安全、更快）
ssh-keygen -t ed25519 -C "your.email@example.com"

# 如果系统不支持 Ed25519，使用 RSA
# ssh-keygen -t rsa -b 4096 -C "your.email@example.com"

查看和复制公钥

# 查看公钥内容
cat ~/.ssh/id_ed25519.pub
# 或
cat ~/.ssh/id_rsa.pub

# 复制公钥到剪贴板（Linux/macOS）
cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard
# 或
cat ~/.ssh/id_ed25519.pub | pbcopy  # macOS

# 复制公钥到剪贴板（WSL/Windows）
cat ~/.ssh/id_ed25519.pub | clip.exe

添加公钥到 Git 服务器

GitHub

访问 GitHub SSH 设置
点击 New SSH key
输入标题（如 "Debian Server"）
粘贴公钥内容
点击 Add SSH key

GitLab

访问 GitLab SSH 设置
点击 Add new key
粘贴公钥内容
点击 Add key

Gitee（码云）

访问 Gitee SSH 设置
点击 添加公钥
粘贴公钥内容
点击确定

启动 SSH 代理并添加密钥

# 启动 ssh-agent
eval "$(ssh-agent -s)"

# 添加私钥到 ssh-agent
ssh-add ~/.ssh/id_ed25519
# 或
ssh-add ~/.ssh/id_rsa

# 查看已添加的密钥
ssh-add -l

配置 SSH 自动加载

编辑 ~/.ssh/config：

nano ~/.ssh/config

添加以下内容：

Host *
    AddKeysToAgent yes
    IdentityFile ~/.ssh/id_ed25519

验证 SSH 连接

测试 GitHub 连接

# 测试 GitHub SSH 连接
ssh -T git@github.com

# 成功输出示例：
# Hi username! You've successfully authenticated, but GitHub does not provide shell access.

测试 GitLab 连接

# 测试 GitLab SSH 连接
ssh -T git@gitlab.com

# 成功输出示例：
# Welcome to GitLab, @username!

测试 Gitee 连接

# 测试 Gitee SSH 连接
ssh -T git@gitee.com

# 成功输出示例：
# Hi username! You've successfully authenticated, but Gitee does not provide shell access.

多平台 SSH 配置

当需要同时使用多个 Git 服务（如 GitHub、GitLab、Gitee）时，可以为每个平台生成不同的 SSH 密钥。

为不同平台生成独立密钥

# 为 GitHub 生成密钥
ssh-keygen -t ed25519 -C "your.email@example.com" -f ~/.ssh/id_ed25519_github

# 为 GitLab 生成密钥
ssh-keygen -t ed25519 -C "your.email@example.com" -f ~/.ssh/id_ed25519_gitlab

# 为 Gitee 生成密钥
ssh-keygen -t ed25519 -C "your.email@example.com" -f ~/.ssh/id_ed25519_gitee

配置 SSH config 文件

创建或编辑 ~/.ssh/config：

nano ~/.ssh/config

添加以下配置：

# GitHub
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_github
    IdentitiesOnly yes

# GitLab
Host gitlab.com
    HostName gitlab.com
    User git
    IdentityFile ~/.ssh/id_ed25519_gitlab
    IdentitiesOnly yes

# Gitee
Host gitee.com
    HostName gitee.com
    User git
    IdentityFile ~/.ssh/id_ed25519_gitee
    IdentitiesOnly yes

配置说明：

Host: 别名，可以使用简短名称（如 gh 代替 github.com）
HostName: 实际的服务器地址
User: 登录用户名（Git 服务统一使用 git）
IdentityFile: 指定的私钥文件路径
IdentitiesOnly yes: 只使用指定的 IdentityFile，不使用默认的 ssh-agent

添加所有密钥到 ssh-agent

# 启动 ssh-agent
eval "$(ssh-agent -s)"

# 添加所有密钥
ssh-add ~/.ssh/id_ed25519_github
ssh-add ~/.ssh/id_ed25519_gitlab
ssh-add ~/.ssh/id_ed25519_gitee

# 查看已添加的密钥
ssh-add -l

使用别名简化操作

可以在 ~/.ssh/config 中使用简短的别名：

# GitHub - 使用简短别名
Host gh
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_github

# GitLab - 使用简短别名
Host gl
    HostName gitlab.com
    User git
    IdentityFile ~/.ssh/id_ed25519_gitlab

# Gitee - 使用简短别名
Host gee
    HostName gitee.com
    User git
    IdentityFile ~/.ssh/id_ed25519_gitee

使用别名克隆仓库：

# 使用完整域名
git clone git@github.com:username/repo.git

# 使用别名
git clone git@gh:username/repo.git

为不同仓库配置不同的用户

如果需要在同一个机器上使用不同的 Git 用户身份，可以为每个仓库单独配置：

# 进入项目目录
cd /path/to/project

# 为该仓库配置用户名和邮箱
git config user.name "Work Name"
git config user.email "work@company.com"

# 查看配置
git config user.name
git config user.email

或者使用条件包含（Git 2.13+）：

编辑 ~/.gitconfig：

nano ~/.gitconfig

添加：

[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work

[includeIf "gitdir:~/personal/"]
    path = ~/.gitconfig-personal

创建工作配置文件 ~/.gitconfig-work：

nano ~/.gitconfig-work

添加：

[user]
    name = Your Work Name
    email = work@company.com

创建个人配置文件 ~/.gitconfig-personal：

nano ~/.gitconfig-personal

添加：

[user]
    name = Your Personal Name
    email = personal@gmail.com

常见问题

1. SSH 连接超时或失败

错误信息：

ssh: connect to host github.com port 22: Connection timed out

解决方法：

# 方法1：使用 SSH over HTTPS（端口 443）
# 编辑 ~/.ssh/config
nano ~/.ssh/config

# 添加以下内容
Host github.com
    Hostname ssh.github.com
    Port 443
    User git

# 测试连接
ssh -T git@github.com

# 方法2：配置代理（如果使用代理）
Host github.com
    Hostname github.com
    User git
    ProxyCommand nc -X 5 -x 192.168.100.1:10808 %h %p

2. 权限拒绝（Permission denied）

错误信息：

Permission denied (publickey)

解决方法：

# 1. 检查密钥是否存在
ls -al ~/.ssh

# 2. 确认公钥已添加到 Git 服务器
cat ~/.ssh/id_ed25519.pub
# 复制并添加到 GitHub/GitLab/Gitee

# 3. 测试 SSH 连接（使用 -v 查看详细信息）
ssh -vT git@github.com

# 4. 确保使用正确的密钥
ssh-add ~/.ssh/id_ed25519

3. Git 提交时用户名不正确

解决方法：

# 查看当前配置
git config user.name
git config user.email

# 修改当前仓库配置
git config user.name "Correct Name"
git config user.email "correct@email.com"

# 修改最后一次提交（谨慎使用）
git commit --amend --author="Correct Name <correct@email.com>"

4. 多个密钥冲突

问题： SSH 默认尝试所有密钥，导致服务器拒绝连接。

解决方法：

在 ~/.ssh/config 中为每个 Host 添加 IdentitiesOnly yes：

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

5. SSH 密钥密码短语遗忘

解决方法：

# 生成新密钥
ssh-keygen -t ed25519 -C "your.email@example.com"

# 删除旧密钥的密码短语（不推荐）
openssl rsa -in ~/.ssh/id_rsa -out ~/.ssh/id_rsa_nopass

6. Git 仓库权限问题

错误信息：

fatal: detected dubious ownership in repository at '/path/to/repo'

解决方法：

# 添加仓库到安全目录
git config --global --add safe.directory /path/to/repo

# 或添加整个目录树
git config --global --add safe.directory '*'

最佳实践

使用 Ed25519 密钥：更安全、更快速
为不同平台使用不同密钥：提高安全性和可管理性
为密钥设置密码短语：增强安全性
定期审查 SSH 密钥：删除不使用的密钥
使用条件包含：为不同项目配置不同的用户身份
启用两步验证：在 Git 服务器上启用 2FA
备份 SSH 密钥：安全地备份私钥文件

参考资源

文档版本： v1.0 更新日期： 2026-02-06 维护者： 开发团队

目录​

基础配置​

配置用户名和邮箱​

查看当前配置​

设置全局用户名和邮箱​

为特定仓库设置不同的用户名和邮箱​

SSH 密钥配置​

检查现有 SSH 密钥​

生成新的 SSH 密钥​

生成 RSA 密钥（传统方式）​

生成 Ed25519 密钥（推荐）​

查看和复制公钥​

添加公钥到 Git 服务器​

GitHub​

GitLab​

Gitee（码云）​

启动 SSH 代理并添加密钥​

配置 SSH 自动加载​

验证 SSH 连接​

测试 GitHub 连接​

测试 GitLab 连接​

测试 Gitee 连接​

多平台 SSH 配置​

为不同平台生成独立密钥​

配置 SSH config 文件​

添加所有密钥到 ssh-agent​

使用别名简化操作​

为不同仓库配置不同的用户​

常见问题​

1. SSH 连接超时或失败​

2. 权限拒绝（Permission denied）​

3. Git 提交时用户名不正确​

4. 多个密钥冲突​

5. SSH 密钥密码短语遗忘​

6. Git 仓库权限问题​

最佳实践​

参考资源​

目录

基础配置

配置用户名和邮箱

查看当前配置

设置全局用户名和邮箱

为特定仓库设置不同的用户名和邮箱

SSH 密钥配置

检查现有 SSH 密钥

生成新的 SSH 密钥

生成 RSA 密钥（传统方式）

生成 Ed25519 密钥（推荐）

查看和复制公钥

添加公钥到 Git 服务器

GitHub

GitLab

Gitee（码云）

启动 SSH 代理并添加密钥

配置 SSH 自动加载

验证 SSH 连接

测试 GitHub 连接

测试 GitLab 连接

测试 Gitee 连接

多平台 SSH 配置

为不同平台生成独立密钥

配置 SSH config 文件

添加所有密钥到 ssh-agent

使用别名简化操作

为不同仓库配置不同的用户

常见问题

1. SSH 连接超时或失败

2. 权限拒绝（Permission denied）

3. Git 提交时用户名不正确

4. 多个密钥冲突

5. SSH 密钥密码短语遗忘

6. Git 仓库权限问题

最佳实践

参考资源