IntelliJ IDEA配置Gitee私人令牌的完整指南(2025 年最新版)_Java

前言

随着代码安全意识的提升，gitee（码云）已全面弃用明文密码进行 git 操作，转而强制使用 私人令牌（personal access token, pat） 进行身份认证。对于使用 intellij idea 的开发者而言，正确配置 gitee 账号与令牌，是实现代码推送、拉取、同步等操作的前提。

然而，许多用户在配置过程中常遇到诸如“授权后显示 404”、“登录失败”、“凭证错误”等问题。

一、为什么需要私人令牌？

gitee 自 2021 年起逐步取消对 git 操作中明文密码的支持，主要原因包括：

防止密码泄露与暴力破解；
提高账户安全性；
支持细粒度权限控制（如仅允许读仓库、不允许删除项目等）；

因此，无论你是通过 https 还是 ide 插件连接 gitee，都必须使用私人令牌替代密码。

二、配置方式概览

方式	说明	推荐度
✅ gitee 插件 + 私人令牌登录	使用官方插件，通过 token 登录，管理方便	⭐⭐⭐⭐⭐（推荐）
❌ oauth 授权登录（log in via gitee）	跳转浏览器授权，但常因回调失败导致 404	⭐（不推荐）
✅ https + token 嵌入 url	直接在远程地址中嵌入 `用户名:令牌`	⭐⭐⭐⭐（备选）
✅ ssh 密钥认证	无需令牌，使用 ssh 公钥	⭐⭐⭐⭐（推荐，另文详述）

本文重点讲解前两种基于 私人令牌 的 https 配置方式。

三、步骤详解：创建 gitee 私人令牌

3.1 登录 gitee 并进入个人设置

访问 https://gitee.com 并登录你的账号。
点击右上角头像，选择「个人设置」。

3.2 创建私人令牌

在左侧菜单中找到并点击「私人令牌」。
点击「生成新令牌」按钮。
填写以下信息：

字段	建议值	说明
令牌名称	`idea-token` 或 `workstation-token`	便于识别用途
有效期	6个月或 1年	不建议永久，便于安全管理
权限范围	至少勾选 `repo` 和 `user_info`	`repo`：读写仓库；`user_info`：读取用户信息

可选权限：

admin_repo_hook：管理 webhook
projects：访问项目管理 api
pages：管理 gitee pages

点击「生成」按钮。

3.3 复制并保存令牌

生成后，页面会显示一串类似 abc123xyz456 的令牌字符串。
此字符串仅显示一次，请立即复制并安全保存（建议使用密码管理器如 1password、bitwarden）。
关闭页面后无法再次查看，若丢失需重新生成。

在这里插入图片描述

四、在 intellij idea 中配置 gitee 账号（推荐方案）

4.1 安装 gitee 插件（如未安装）

打开 intellij idea。
进入菜单：
- windows/linux：file → settings → plugins
- macos：intellij idea → preferences → plugins
在 marketplace 中搜索 gitee。
找到由 gitee 官方提供的插件（注意不是第三方），点击 install。
安装完成后重启 idea。

在这里插入图片描述

插件功能：支持在 idea 内直接登录 gitee、浏览仓库、创建 issue、管理 pull request 等。

4.2 使用私人令牌登录 gitee 账号

进入设置：

file → settings → version control → gitee

点击右上角的 + 号，选择 「log in with tokens」。

不要选择「log in via gitee」，该方式依赖 oauth 回调，常因本地服务未启动或 gitee 配置问题导致授权后跳转 localhost 失败，显示 404。

在这里插入图片描述

填写登录信息：

字段	值
host	`https://gitee.com`
access token	粘贴你刚刚复制的私人令牌
refresh token	留空（gitee 不支持刷新令牌）

重要说明：gitee 的私人令牌是静态的，没有刷新机制，因此 refresh token 字段无需填写。

点击 add account。若配置正确，idea 会显示登录成功，并列出你的 gitee 用户名和邮箱。

在这里插入图片描述

五、验证配置是否成功

方法一：通过 gitee 插件验证

回到 settings → version control → gitee，确认账号已显示为已登录状态。

方法二：执行 git 操作

打开一个已关联 gitee 远程仓库的项目。
尝试执行：
- vcs → git → pull
- 或 push
若操作成功，无认证错误提示，说明配置正确。

六、备选方案：直接配置 git 远程 url（无需插件）

如果你不想使用 gitee 插件，也可以通过修改 git 远程地址的方式使用令牌。

6.1 修改远程仓库 url

在终端或 idea 的 git 工具中执行：

git remote set-url origin https://<用户名>:<私人令牌>@gitee.com/<用户名>/<仓库名>.git

示例：

git remote set-url origin https://zhangsan:abc123xyz@gitee.com/zhangsan/my-project.git

6.2 配置凭据存储（可选）

避免每次操作都输入凭证：

# 将凭据保存到磁盘（明文，注意安全）
git config --global credential.helper store

# 或使用缓存（内存中，重启后清除）
git config --global credential.helper cache

使用 store 时，凭据会以明文保存在 ~/.git-credentials 文件中，请确保系统安全。

七、常见问题与解决方案

问题	原因	解决方案
授权后显示 404	oauth 回调失败，idea 无法接收令牌	改用「log in with tokens」方式
认证失败 / 403	令牌错误、过期或权限不足	检查令牌是否复制正确，重新生成并确保勾选 `repo` 权限
push 成功但 pull 失败	凭据未持久化	配置 `credential.helper` 或重新登录
插件无法安装	网络问题或仓库不可达	检查网络，尝试切换镜像源