核心结论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输入以下命令替换为你的邮箱ssh-keygen -t ed25519 -C 你的Gitee/GitHub邮箱⚠️ 排雷时刻提示Enter file in which to save the key保存路径直接按回车千万别填仓库地址。提示Enter passphrase设置密码直接按两次回车留空以后拉取代码无需输密码。3. 复制并添加公钥执行命令查看并复制公钥内容cat ~/.ssh/id_ed25519.pub终端会输出一长串以ssh-ed25519开头的字符完整复制。登录 Gitee/GitHub进入设置 - SSH 公钥粘贴并保存。4. 复制并添加公钥登录 Gitee 网站。点击右上角你的头像选择设置。在左侧菜单栏找到并点击SSH 公钥。在“添加公钥”区域标题随便填比如“我的电脑”公钥框里粘贴你刚才复制的那一大段字符串。点击确定此时可能需要你输入 Gitee 的登录密码来确认5. 验证连接在终端输入ssh -T gitgitee.com # 或 gitgithub.com如果提示Hi 你的用户名! Youve 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 自带的客户端C:\Program Files\Git\usr\bin\ssh.exe点击 Apply 保存。再次推送丝滑通过。⚠️ 三、 踩坑排查排雷Clone 遇到目录非空如果你在已存在的文件夹里直接执行git cloneGit 会直接报错并中止操作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地址直接拉取最新代码即可git pull origin master # 或 git pull origin main如果提示没有权限只需按第一步重新配置一次 SSH 公钥即可。️ 四、 仓库防污染.gitignore 的重要性在提交代码前如果误将虚拟环境.venv和 IDE 配置.idea提交会导致仓库极其臃肿且在不同电脑间引发路径冲突。在项目根目录新建.gitignore文件填入以下内容# 忽略虚拟环境 .venv/ venv/ # 忽略 IDE 配置 .idea/ .vscode/ # 忽略 Python 缓存 __pycache__/ *.pyc # 忽略环境变量保护 API Key .env如果已经误提交在终端执行git rm -r --cached .venv .idea清除版本控制缓存不会删除本地文件然后重新 Commit。