前言在上一篇文章《Git 11Git 创建新的远程分支并推送本地最新代码》中主要介绍了如何从已有 Git 项目创建新的远程分支并将本地最新代码推送到远程仓库。实际开发过程中还有一个非常容易被忽略、但又经常导致git push失败的问题——Git 认证。尤其是在服务器迁移、电脑更换、项目通过 ZIP 压缩包重新下载、Git 远程地址发生变化之后经常会遇到Incorrect username or password (access token) fatal: Authentication failed或者Permission denied (publickey)这类问题表面上看是“Git Push 失败”实际上很多时候代码、分支、Commit 都没有问题真正出问题的是远程仓库的身份认证。本文就结合一次实际项目迁移场景从HTTPS 认证 → Access Token → SSH Key → Gitee SSH 验证 → 修改远程地址 → 新分支推送完整梳理 Git 与 Gitee 的认证流程。本文重点介绍SSH 认证方式并解释为什么在日常开发中SSH 往往比 HTTPS 更适合作为长期使用的 Git 认证方案。本文使用 Gitee 作为远程 Git 仓库示例GitHub、GitLab 等平台的 SSH 使用思路基本一致。一、为什么 Git Push 会涉及认证1.1 Git Push 本质上是在访问远程仓库很多刚开始使用 Git 的开发者会认为gitadd.gitcommitgitpush只是把代码“上传”到服务器。实际上git push做的是将本地仓库中的 Commit、分支等 Git 对象更新到远程仓库。因此远程仓库必须确认“你是谁你有没有权限修改这个仓库”这就是Git 认证。例如本地电脑 │ │ git push ↓ Gitee │ ├── 身份认证 │ ├── 仓库权限检查 │ └── 接受 / 拒绝 PushGit 官方文档中也明确说明git push用于更新远程仓库中的引用并将远程尚不存在的必要 Git 数据发送到远程仓库。1.2 Git 认证与 Git 提交不是一回事这是一个非常重要的概念。例如执行gitcommit-m修复接口问题成功只代表代码已经保存到了本地 Git 仓库。而执行gitpush成功才代表代码已经通过认证并上传到了远程仓库。所以出现git commit 成功 git push 失败完全正常。例如本地 Git │ ├── git add ✅ ├── git commit ✅ │ └── git push ❌ 认证失败此时本地代码和 Commit 并没有丢失。1.3 常见的 Git 远程认证方式Git 访问远程仓库时常见的方式主要有方式示例特点HTTPShttps://gitee.com/user/repo.git简单直观HTTPS Token用户名 Access Token比传统密码方式更适合现代认证SSHgitgitee.com:user/repo.git配置后使用方便适合长期开发本文重点介绍其中的HTTPS 认证问题排查 SSH Key 认证。二、HTTPS 认证失败Incorrect username or password2.1 常见报错在使用 HTTPS 协议推送代码时如果遇到以下错误提示remote: Incorrect username or password (access token) fatal: Authentication failed首先请不要怀疑自己的代码有问题。这个错误信息实际上表明Git 已经连接到了 Gitee但身份认证没有通过。Gitee 官方帮助文档也将fatal: Authentication failed归类为 Git 客户端认证问题并建议检查 HTTPS 用户名/密码或改用 SSH。2.2 为什么会出现这种问题常见原因包括① Gitee 用户名或密码错误例如Username错误 Password错误自然无法通过认证。② Windows 保存了旧的 Gitee 凭据Windows 可能缓存了以前的git:https://gitee.com如果之前使用的是旧账号或者旧密码即使现在输入正确账号也可能继续使用缓存信息。可以进入控制面板 → 用户账户 → 凭据管理器 → Windows 凭据检查git:https://gitee.com相关凭据。Gitee 官方也提供了 Windows 凭据管理器的排查方法。2.3 Access Token 是什么现代 Git 服务通常不会推荐直接使用账户登录密码进行 Git 操作而是使用Access Token / Personal Access Token等方式完成认证。可以简单理解为Gitee 登录密码 ↓ 用于登录网站 Git Access Token ↓ 用于程序 / Git 客户端进行身份认证因此如果 HTTPS Push 要求Username: Password:这里的 Password 在某些配置下实际上应当使用对应的Access Token而不是直接填写网站登录密码。2.4 HTTPS 认证到底要不要继续使用当然可以。HTTPS 的优点是配置简单不需要管理 SSH Key临时使用比较方便很适合偶尔操作 Git 的场景但是长期开发时可能遇到Token 过期 凭据缓存 账号切换 Windows Credential Manager 重新输入认证信息因此如果是每天都要开发、频繁 Push 的项目我更推荐配置SSH Key。三、SSH Key更适合长期 Git 开发3.1 SSH 认证是什么SSH 可以理解成提前让自己的电脑与 Gitee 建立可信的身份关系。基本结构如下你的电脑 │ ├── 私钥 id_rsa │ └── 公钥 id_rsa.pub │ ↓ Gitee其中私钥id_rsa只保存在自己的电脑上。公钥id_rsa.pub可以添加到 Gitee。之后 Git 使用 SSH 地址gitgitee.com:用户名/仓库名.git进行 Push/Pull。Gitee 官方文档明确提供了基于 SSH 协议的 Git 服务并支持通过 SSH 公钥完成身份认证。3.2 检查电脑是否已经存在 SSH KeyWindows PowerShellGet-ChildItem~/.ssh如果看到id_rsa id_rsa.pub known_hosts或者id_ed25519 id_ed25519.pub known_hosts说明电脑已经存在 SSH Key。例如C:\Users\Lee\.ssh id_rsa id_rsa.pub known_hosts其中id_rsa是私钥。id_rsa.pub是公钥。注意千万不要把id_rsa私钥上传到 Gitee也不要发送给别人。需要添加到 Gitee 的是id_rsa.pub3.3 如果没有 SSH Key如何生成如果电脑没有 SSH Key可以生成新的 Key。推荐使用 Ed25519ssh-keygen-t ed25519-C你的邮箱然后按照提示操作。生成后一般会得到id_ed25519 id_ed25519.pubGitee 官方当前文档同样给出了 Ed25519 SSH Key 的生成方式。四、将 SSH 公钥添加到 Gitee4.1 查看 SSH 公钥如果使用的是 RSAGet-Content~/.ssh/id_rsa.pub如果使用的是 Ed25519Get-Content~/.ssh/id_ed25519.pub会得到类似ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...或者ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAA...复制整行内容。4.2 在 Gitee 中添加 SSH 公钥进入 Gitee 后找到个人设置 → SSH 公钥 → 添加 SSH 公钥然后标题Windows-PC 公钥 粘贴 id_rsa.pub 或 id_ed25519.pub 内容保存即可。Gitee 官方文档中也提供了 SSH 公钥添加以及认证测试方法。4.3 为什么 SSH Key 配置一次以后就方便配置完成之后本地电脑 │ │ SSH ↓ Gitee │ ├── 身份验证 ├── 权限验证 └── Git Push以后执行git push通常不再需要反复输入 Gitee 用户名和 Token。这也是为什么对于长期维护的项目SSH 是非常实用的认证方式。五、验证 SSH 是否配置成功5.1 使用 ssh -T 测试执行ssh-T gitgitee.com第一次使用时可能出现The authenticity of host gitee.com cant be established.输入yes即可。5.2 什么结果才算成功如果出现Hi xxx! Youve successfully authenticated, but GITEE.COM does not provide shell access.很多人看到does not provide shell access会以为失败了。其实不是。真正关键的是successfully authenticated这表示SSH 身份认证已经成功。Gitee 官方文档给出的成功验证结果也是类似的successfully authenticated提示。5.3 如果出现 Permission denied (publickey)例如Permission denied (publickey).说明 SSH 没有成功找到或使用有效的公钥。重点检查1. SSH Key 是否存在 2. 公钥是否添加到了正确的 Gitee 账号 3. 当前 Git 是否使用了正确的私钥 4. SSH 地址是否正确 5. 多 SSH Key 时是否需要配置 ssh-agent / ssh configGitee 官方也将Permission denied (publickey)归为 SSH 公钥配置问题。六、将 Git 远程地址从 HTTPS 改成 SSH6.1 查看当前远程地址执行git remote-v如果看到origin https://gitee.com/njust_365/jiaotong.git (fetch) origin https://gitee.com/njust_365/jiaotong.git (push)说明当前使用的是 HTTPS。Gitee 的 Git 基础操作文档也说明了git remote -v可以查看当前远程仓库地址。6.2 修改为 SSH 地址执行git remoteset-urlorigin gitgitee.com:njust_365/jiaotong.git然后再次检查git remote-v应该变成origin gitgitee.com:njust_365/jiaotong.git (fetch) origin gitgitee.com:njust_365/jiaotong.git (push)这样以后这个项目的 Git 网络操作就会通过 SSH 进行。七、ZIP 压缩包项目如何重新建立 Git 分支7.1 为什么 ZIP 项目容易出现 Git 问题这是一个非常典型的场景。Gitee 支持通过 ZIP 下载代码但官方文档明确说明下载 ZIP 得到的是代码内容不包含完整 Git 版本历史。因此Git Clone ↓ 代码 .git 提交历史 分支信息 下载 ZIP ↓ 主要得到代码文件两者不是一回事。所以如果服务器迁移后你重新下载 ZIP再继续开发就可能需要重新建立本地 Git 仓库。7.2 初始化本地 Git 仓库进入项目cd D:\Njust_File\Work_Codes\Dmx\jiaotong-main执行git init然后git status如果看到No commits yet说明当前仓库没有提交历史。7.3 设置新的开发分支例如git branch-M dev-server-migration这里的dev-server-migration可以根据实际项目修改。例如dev develop feature/server-migration dev-v2对于服务器迁移后的项目dev-server-migration的含义比较清晰。八、提交并推送当前最新版代码8.1 添加代码git add.然后检查git status如果看到Changes to be committed:说明文件已经进入暂存区。8.2 创建第一次 Commit执行git commit-mchore: 保存服务器迁移后的最新版代码第一次提交可能看到[dev-server-migration (root-commit) 247da2f]这里的root-commit是正常现象。它表示这是这个本地 Git 仓库的第一个 Commit。8.3 推送到 Gitee 新分支远程地址确认是 SSH 后git push-u origin dev-server-migration成功后类似[new branch] dev-server-migration - dev-server-migration branch dev-server-migration set up to track origin/dev-server-migration这意味着远程 Gitee 中会自动创建dev-server-migration分支。Git 官方文档说明git push -u/--set-upstream会为当前分支设置上游跟踪关系因此之后可以直接使用无参数的git push。九、如何确保 main 主分支不被修改这是实际项目迁移过程中最需要注意的一点。如果你的目标是main ↓ 原有稳定代码 ↓ 保持不动 dev-server-migration ↓ 服务器迁移后的最新版 ↓ 以后继续开发那么第一次推送时一定要明确指定git push-u origin dev-server-migration而不是git push origin main更不要随意使用git push-f9.1 为什么git push -u origin dev-server-migration是安全的因为命令已经明确指定远程仓库origin 远程目标dev-server-migration所以 Git 会把当前本地分支推送到远程同名分支。Git 的 Push 语法本身就是通过远程仓库和 refspec 指定推送目标因此明确写出分支名是一个很好的安全习惯。十、第一次推送完成后如何检查10.1 查看本地分支git branch应该* dev-server-migration10.2 查看远程分支git branch-r应该origin/dev-server-migration10.3 查看本地 远程全部分支git branch-a应该类似* dev-server-migration remotes/origin/dev-server-migration如果本地仓库本来没有origin/main的远程跟踪信息那么这里暂时看不到origin/main不代表 Gitee 上的 main 被删除了。这点非常容易误解。10.4 查看工作区是否干净git status理想状态On branch dev-server-migration Your branch is up to date with origin/dev-server-migration. nothing to commit, working tree clean看到nothing to commit, working tree clean基本就说明当前代码已经全部提交。十一、以后日常开发怎么操作完成第一次git push-u origin dev-server-migration之后就不需要每次写完整分支名了。开发前git pull开发完成git add.git commit-m修复XXX问题git push因为dev-server-migration ↓ origin/dev-server-migration已经建立了跟踪关系。Git 官方文档也说明上游分支会作为后续pull、fetch和默认push等操作的重要目标。十二、Git Gitee 认证问题排查12.1Incorrect username or password (access token)典型remote: Incorrect username or password (access token) fatal: Authentication failed优先检查① HTTPS 用户名是否正确 ② Token 是否正确 ③ Windows 凭据管理器是否保存旧凭据 ④ 当前账号是否拥有仓库 Push 权限 ⑤ 是否可以直接切换 SSH如果长期开发推荐HTTPS → SSHGitee 官方针对该错误也给出了 HTTPS 凭据检查和改用 SSH 的解决路径。12.2Permission denied (publickey)检查Get-ChildItem~/.ssh然后ssh-T gitgitee.com重点确认SSH Key 是否存在 ↓ 公钥是否添加到正确账号 ↓ SSH 是否能认证 ↓ remote 是否使用 gitgitee.com12.3Could not resolve hostname例如Could not resolve hostname gitee.com这通常不是 Git 分支问题而是DNS 网络 代理 服务器网络环境需要从网络层面排查。12.4 RSA SSH Key 突然失效如果以前配置过id_rsa后来升级 Git/OpenSSH 后突然出现 SSH 认证问题也要注意算法兼容性。Gitee 官方曾针对 OpenSSH 8.8 后 RSA-SHA1 支持变化提供过专门说明并建议必要时改用 Ed25519 Key。新环境优先推荐ssh-keygen-t ed25519-C你的邮箱十三、几个非常容易踩坑的地方13.1 不要把私钥上传到仓库错误id_rsa正确id_rsa.pub记住.pub是公钥可以添加到 Gitee没有.pub后缀的通常是私钥绝对不要公开。13.2 不要看到 Push 失败就重新 Commit例如git commit ✅ git push ❌不要重新git add . git commit先解决认证问题。因为 Commit 已经保存在本地。13.3 不要为了 Push 失败直接git push -f特别是git push-f origin main非常危险。--force会允许非 Fast-forward 更新在错误情况下可能覆盖远程分支历史。Git 官方 Push 文档也明确将强制更新作为特殊操作处理。13.4 ZIP 下载和 Git Clone 不要混为一谈如果以后希望完整保留Commit Branch Tag Remote History优先git clone而不是下载 ZIPZIP 更适合只需要某个版本的代码文件。13.5.env等配置文件要特别小心项目中经常存在.env .env.local .env.production里面可能包含API 地址 数据库地址 账号 Token Secret 私钥因此正式执行git add.之前最好确认.gitignore。本文为了突出 Git 认证流程不展开.gitignore的具体规则但在实际项目中这是必须检查的一步。十四、完整实战从 ZIP 代码到 Gitee SSH 新分支最后把整个流程压缩成一个实际场景。假设Gitee https://gitee.com/njust_365/jiaotong 远程稳定分支 main 本地 D:\Njust_File\Work_Codes\Dmx\jiaotong-main目标main ← 不修改 dev-server-migration ← 保存当前最新版完整命令cd D:\Njust_File\Work_Codes\Dmx\jiaotong-main git init git status git remote-v git branch-M dev-server-migrationGet-ChildItem~/.sshGet-Content~/.ssh/id_rsa.pub ssh-T gitgitee.com git remoteset-urlorigin gitgitee.com:njust_365/jiaotong.git git remote-v git add.git status git commit-mchore: 保存服务器迁移后的最新版代码git push-u origin dev-server-migration git branch-a git status最终形成Gitee │ ┌─────────┴─────────┐ │ │ main dev-server-migration │ │ 原有稳定版本 当前最新版代码 │ │ 不修改 持续开发 │ ↓ git push十五、本文总结这次重点不是单纯介绍git branch git push而是解决一个实际开发中非常常见的问题代码已经准备好了Git 也没有问题但是 Push 时认证失败怎么办可以把整个思路记成① 确认 Git 仓库 ↓ ② 确认远程地址 ↓ ③ 确认认证方式 ↓ ④ HTTPS 失败 → 检查账号 / Token / 凭据 ↓ ⑤ 长期开发 → 推荐 SSH ↓ ⑥ 检查 SSH Key ↓ ⑦ Gitee 添加 SSH 公钥 ↓ ⑧ ssh -T gitgitee.com ↓ ⑨ remote 切换到 SSH ↓ ⑩ 创建新分支 ↓ ⑪ git add ↓ ⑫ git commit ↓ ⑬ git push -u origin 新分支其中最值得记住的几个命令是# 查看 SSH KeyGet-ChildItem~/.ssh# 查看 SSH 公钥Get-Content~/.ssh/id_rsa.pub# 测试 Gitee SSHssh-T gitgitee.com# 查看远程地址git remote-v# 切换 SSH 远程地址git remoteset-urlorigin gitgitee.com:用户名/仓库名.git# 第一次推送新分支git push-u origin 新分支名# 查看所有分支git branch-a如果是长期维护的项目个人更推荐**SSH Key SSH Remote 独立开发分支**这种组合。认证问题解决后Git 的日常工作流就会重新回到最简单的状态git pull# 修改代码git add.git commit-m修改说明git push认证只需要认真配置一次之后就可以把精力放回代码本身。参考资料Gitee生成/添加 SSH 公钥。GiteeGit 操作常见问题。GiteeHTTPS 推送Incorrect username or password (access token)排查。GiteeGit 仓库基础操作。Git 官方git push。十六、更多操作更多 Git 实战内容请看 Git / GitHub / GitLab / Gitee 个人专栏本文属于 Git 企业级实战系列持续更新 Git 相关干货欢迎关注我的 CSDN 专栏GitHub / GitLab / Gitee​