IntelliJ IDEA 配置 Gitee 私人令牌完整指南（2025 年最新版）
前言
随着代码安全意识的提升，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：管理 Webhookprojects：访问项目管理 APIpages：管理 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
- Windows/Linux：
- 在 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:[email protected]/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 或重新登录 |
| 插件无法安装 | 网络问题或仓库不可达 | 检查网络，尝试切换镜像源 |
