📌 核心结论（TL;DR）
-
首选 Ed25519 ：放弃传统的 RSA 算法，使用更安全、更简短的
ed25519算法生成 SSH 密钥，配置时提示保存路径和密码，一律直接按回车。 -
图形化工具排雷 ：TortoiseGit（小乌龟）默认的 PuTTY 客户端与 Git 原生的 OpenSSH 密钥不兼容，遇到
publickey报错，需在设置中将 SSH Client 切换为 Git 自带的ssh.exe。 -
Clone 保命法则 ：执行
git clone遇到"目标路径非空"报错时，Git 会自动中止，绝不会删除你的本地文件 。需根据情况选择清空目录、备份合并或直接git pull。 -
仓库防污染 ：必须在项目根目录配置
.gitignore文件，排除虚拟环境（.venv）和 IDE 配置（.idea），防止仓库体积臃肿。
🔍 一、 SSH 密钥配置（Ed25519 最佳实践）
在使用 Git 时，SSH 协议可以让我们免去每次推送都要输入账号密码的烦恼。目前，Ed25519 算法因其安全性高、生成速度快，已成为 GitHub 和 Gitee 官方推荐的首选。
1. 检查是否已有SSH密钥
打开 Git Bash，输入 ls -al ~/.ssh。如果看到 id_rsa.pub 或 id_ed25519.pub 这样的文件，说明已有密钥，可以跳到第3步。
2. 生成密钥
打开 Git Bash，输入以下命令（替换为你的邮箱）：
bash
ssh-keygen -t ed25519 -C "你的Gitee/GitHub邮箱"⚠️ 排雷时刻：
-
提示
Enter file in which to save the key（保存路径）：直接按回车（千万别填仓库地址）。 -
提示
Enter passphrase（设置密码）：直接按两次回车（留空，以后拉取代码无需输密码）。
3. 复制并添加公钥
执行命令查看并复制公钥内容：
bash
cat ~/.ssh/id_ed25519.pub终端会输出一长串以 ssh-ed25519 开头的字符，完整复制 。登录 Gitee/GitHub，进入 设置 -> SSH 公钥，粘贴并保存。
4. 复制并添加公钥
-
登录 Gitee 网站。
-
点击右上角你的头像，选择 设置。
-
在左侧菜单栏找到并点击 SSH 公钥。
-
在"添加公钥"区域，标题 随便填（比如"我的电脑"），公钥框里粘贴你刚才复制的那一大段字符串。
-
点击 确定（此时可能需要你输入 Gitee 的登录密码来确认）
5. 验证连接
在终端输入：
bash
ssh -T git@gitee.com # 或 git@github.com如果提示 Hi 你的用户名! You've successfully authenticated, but GITEE.COM does not provide shell access. 或者询问你是否继续连接输入 yes，就说明配置成功了！
💻 二、 TortoiseGit 图形化工具的终极排雷
很多开发者习惯用 TortoiseGit（小乌龟）右键菜单操作，但极易遇到这个经典报错：
No supported authentication methods available (server sent: publickey)
原因 ：TortoiseGit 默认使用自己的 SSH 客户端（PuTTY），而我们刚生成的是 OpenSSH 格式的密钥，两者不兼容。
解决步骤：
-
右键桌面空白处 -> TortoiseGit -> Settings。
-
左侧选择 Network。
-
将右侧的 SSH Client 路径修改为 Git 自带的客户端：
bashC:\Program Files\Git\usr\bin\ssh.exe -
点击 Apply 保存。再次推送，丝滑通过。
⚠️ 三、 踩坑排查排雷：Clone 遇到目录非空
如果你在已存在的文件夹里直接执行 git clone，Git 会直接报错并中止操作：
fatal: destination path '...' already exists and is not an empty directory.
别慌，你的文件绝对不会丢失！ 根据你的情况选择以下方案：
情况 A：文件夹里全是垃圾 / 上次失败的残留
如果你确定里面的文件不需要了，直接手动删除该文件夹，然后重新执行你的 git clone 命令。
情况 B：里面有本地重要代码，需要合并
千万别直接用 clone 覆盖！
-
先把本地文件夹重命名备份（如
_backup）。 -
正常执行
git clone下载全新仓库。 -
把备份文件夹里的重要代码，手动复制到新克隆的仓库里。
情况 C：这个文件夹本身就是个 Git 仓库（有 .git 隐藏文件夹）
如果你之前就克隆过，只是重装了系统，根本不需要重新 clone！
-
在终端
cd进入该文件夹。 -
检查远程连接是否还在：
git remote -v。 -
如果能看到
origin地址，直接拉取最新代码即可：bashgit pull origin master # 或 git pull origin main -
如果提示没有权限，只需按第一步重新配置一次 SSH 公钥即可。
🛡️ 四、 仓库防污染：.gitignore 的重要性
在提交代码前，如果误将虚拟环境（.venv）和 IDE 配置（.idea）提交，会导致仓库极其臃肿，且在不同电脑间引发路径冲突。
在项目根目录新建 .gitignore 文件，填入以下内容：
cpp
# 忽略虚拟环境
.venv/
venv/
# 忽略 IDE 配置
.idea/
.vscode/
# 忽略 Python 缓存
__pycache__/
*.pyc
# 忽略环境变量（保护 API Key）
.env- 如果已经误提交 ：在终端执行
git rm -r --cached .venv .idea清除版本控制缓存（不会删除本地文件），然后重新 Commit。