Git 12 ，Git 认证完全指南：HTTPS、Access Token 与 SSH Key 配置，解决 Authentication failed 与 SSH 推送问题

原创于 2026-08-19 14:30:00 发布 · 761 阅读

12 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

Vue

前端开发

Git / GitHub / GitLab / Gitee

话题

#CodingPlan·八月创作之星博客挑战赛

前言

在上一篇文章 《Git 11，Git 创建新的远程分支，并推送本地最新代码》 中，主要介绍了如何从已有 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 的开发者会认为：

git add .
git commit
git push

只是把代码“上传”到服务器。

实际上，git push 做的是：

将本地仓库中的 Commit、分支等 Git 对象更新到远程仓库。

因此远程仓库必须确认：

“你是谁？你有没有权限修改这个仓库？”

这就是 Git 认证。

例如：

本地电脑
   │
   │ git push
   ↓
Gitee
   │
   ├── 身份认证
   │
   ├── 仓库权限检查
   │
   └── 接受 / 拒绝 Push

Git 官方文档中也明确说明，git push 用于更新远程仓库中的引用，并将远程尚不存在的必要 Git 数据发送到远程仓库。

1.2 Git 认证与 Git 提交不是一回事

这是一个非常重要的概念。

例如执行：

git commit -m "修复接口问题"

成功，只代表：

代码已经保存到了本地 Git 仓库。

而执行：

git push

成功，才代表：

代码已经通过认证并上传到了远程仓库。

所以出现：

git commit 成功
git push 失败

完全正常。

例如：

本地 Git
   │
   ├── git add        ✅
   ├── git commit     ✅
   │
   └── git push       ❌ 认证失败

此时本地代码和 Commit 并没有丢失。

1.3 常见的 Git 远程认证方式

Git 访问远程仓库时，常见的方式主要有：

方式	示例	特点
HTTPS	`https://gitee.com/user/repo.git`	简单直观
HTTPS + Token	用户名 + Access Token	比传统密码方式更适合现代认证
SSH	`git@gitee.com:user/repo.git`	配置后使用方便，适合长期开发

本文重点介绍其中的：

HTTPS 认证问题排查 + SSH Key 认证。

在这里插入图片描述

二、HTTPS 认证失败：Incorrect username or password

2.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

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 地址：

git@gitee.com:用户名/仓库名.git

进行 Push/Pull。

Gitee 官方文档明确提供了基于 SSH 协议的 Git 服务，并支持通过 SSH 公钥完成身份认证。

3.2 检查电脑是否已经存在 SSH Key

Windows PowerShell：

Get-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.pub

3.3 如果没有 SSH Key，如何生成？

如果电脑没有 SSH Key，可以生成新的 Key。

推荐使用 Ed25519：

ssh-keygen -t ed25519 -C "你的邮箱"

然后按照提示操作。

生成后一般会得到：

id_ed25519
id_ed25519.pub

Gitee 官方当前文档同样给出了 Ed25519 SSH Key 的生成方式。

在这里插入图片描述

四、将 SSH 公钥添加到 Gitee

4.1 查看 SSH 公钥

如果使用的是 RSA：

Get-Content ~/.ssh/id_rsa.pub

如果使用的是 Ed25519：

Get-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 git@gitee.com

第一次使用时，可能出现：

The authenticity of host 'gitee.com' can't be established.

输入：

yes

即可。

5.2 什么结果才算成功？

如果出现：

Hi xxx! You've 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 config

Gitee 官方也将 Permission denied (publickey) 归为 SSH 公钥配置问题。

六、将 Git 远程地址从 HTTPS 改成 SSH

6.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 remote set-url origin git@gitee.com:njust_365/jiaotong.git

然后再次检查：

git remote -v

应该变成：

origin  git@gitee.com:njust_365/jiaotong.git (fetch)
origin  git@gitee.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 -m "chore: 保存服务器迁移后的最新版代码"

第一次提交可能看到：

[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 -f

9.1 为什么 `git push -u origin dev-server-migration` 是安全的？

因为命令已经明确指定：

远程仓库：origin
远程目标：dev-server-migration

所以 Git 会把当前本地分支推送到远程同名分支。

Git 的 Push 语法本身就是通过远程仓库和 refspec 指定推送目标，因此明确写出分支名是一个很好的安全习惯。

十、第一次推送完成后如何检查？

10.1 查看本地分支

git branch

应该：

* dev-server-migration

10.2 查看远程分支

git branch -r

应该：

origin/dev-server-migration

10.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.1 `Incorrect username or password (access token)`

典型：

remote: Incorrect username or password (access token)
fatal: Authentication failed

优先检查：

① HTTPS 用户名是否正确
② Token 是否正确
③ Windows 凭据管理器是否保存旧凭据
④ 当前账号是否拥有仓库 Push 权限
⑤ 是否可以直接切换 SSH

如果长期开发，推荐：

HTTPS → SSH

Gitee 官方针对该错误也给出了 HTTPS 凭据检查和改用 SSH 的解决路径。

12.2 `Permission denied (publickey)`

检查：

Get-ChildItem ~/.ssh

然后：

ssh -T git@gitee.com

重点确认：

SSH Key 是否存在
        ↓
公钥是否添加到正确账号
        ↓
SSH 是否能认证
        ↓
remote 是否使用 git@gitee.com

12.3 `Could 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

而不是：

下载 ZIP

ZIP 更适合：

只需要某个版本的代码文件。

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-migration

Get-ChildItem ~/.ssh

Get-Content ~/.ssh/id_rsa.pub

ssh -T git@gitee.com

git remote set-url origin git@gitee.com:njust_365/jiaotong.git

git remote -v

git add .

git status

git commit -m "chore: 保存服务器迁移后的最新版代码"

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 git@gitee.com
        ↓
⑨ remote 切换到 SSH
        ↓
⑩ 创建新分支
        ↓
⑪ git add
        ↓
⑫ git commit
        ↓
⑬ git push -u origin 新分支

其中最值得记住的几个命令是：

# 查看 SSH Key
Get-ChildItem ~/.ssh

# 查看 SSH 公钥
Get-Content ~/.ssh/id_rsa.pub

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

# 查看远程地址
git remote -v

# 切换 SSH 远程地址
git remote set-url origin git@gitee.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 公钥。
Gitee：Git 操作常见问题。
Gitee：HTTPS 推送 Incorrect username or password (access token) 排查。
Gitee：Git 仓库基础操作。
Git 官方：git push。