---
url: /dev/2s4hx8pj/index.md
description: >-
  GitHub CLI（gh）安装与使用指南，通过命令行快速完成 GitHub 身份验证，无需手动配置 SSH 密钥或 Personal Access
  Token。
---
# 使用 GitHub CLI 快速登录

GitHub CLI（`gh`）是 GitHub 的官方命令行工具，让你可以直接在终端中完成大多数 GitHub 操作，包括快速登录认证。本文将介绍如何在不同操作系统上安装 `gh` 以及如何使用它快速登录 GitHub。

::: tip 什么是 GitHub CLI？
GitHub CLI 是一个用 Go 编写的开源工具，它将 GitHub 的强大功能带到命令行中。使用 `gh auth login` 命令，可以快速完成 GitHub 的身份验证，无需手动配置 SSH 密钥或处理 Personal Access Token。
:::

## 安装 GitHub CLI

### macOS 安装方法

在 macOS 上，有多种方式可以安装 GitHub CLI：

#### 使用 Homebrew 安装（推荐）

```bash
brew install gh
```

这是最简单快捷的安装方式，Homebrew 会自动处理依赖关系。

#### 使用 MacPorts 安装

```bash
sudo port install gh
```

#### 手动安装

如果不想使用包管理器，也可以从 [GitHub CLI 官方发布页](https://github.com/cli/cli/releases) 下载 `.pkg` 安装包进行手动安装。

### Windows 安装方法

在 Windows 上，同样有多种安装方式：

#### 使用 winget 安装（推荐）

```powershell
winget install --id GitHub.cli
```

Windows Package Manager（winget）是 Windows 10/11 自带的官方包管理器。

#### 使用 Scoop 安装

```powershell
scoop bucket add github-gh https://github.com/cli/scoop.git
scoop install gh
```

#### 使用 Chocolatey 安装

```powershell
choco install gh
```

#### 手动安装

从 [GitHub CLI 官方发布页](https://github.com/cli/cli/releases) 下载 `.msi` 安装包，双击运行安装向导即可。

### Linux 安装方法

虽然你主要关注 macOS 和 Windows，但为了完整性，这里也提供 Linux 的安装方法：

#### Debian/Ubuntu

```bash
type -p curl >/dev/null || sudo apt install curl -y
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
&& sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update \
&& sudo apt install gh
```

#### Fedora/CentOS/RHEL

```bash
sudo dnf install gh
```

::: warning 注意事项
安装完成后，建议重启终端或执行 `hash -r`（bash/zsh）或 `rehash`（fish）来刷新命令缓存。
:::

## 使用 GitHub CLI 登录

安装完成后，使用以下命令进行 GitHub 登录：

```bash
gh auth login
```

### 登录流程

执行登录命令后，`gh` 会引导你完成一系列配置选项：

::: details 步骤 1：选择 GitHub 服务器

```
? What account do you want to log into?
  GitHub.com        # GitHub 公有云服务（通常选择这个）
  GitHub Enterprise Server  # 企业私有部署服务器
```

使用方向键选择 `GitHub.com`，然后按回车确认。
:::

::: details 步骤 2：选择认证方式

```
? What is your preferred protocol for Git operations?
  HTTPS          # 使用 HTTPS 进行 Git 操作
  SSH            # 使用 SSH 密钥进行 Git 操作
```

* **HTTPS**：适合大多数用户，无需额外配置 SSH 密钥
* **SSH**：如果你已经配置了 SSH 密钥，可以选择此选项

使用方向键选择你偏好的协议，按回车确认。
:::

::: details 步骤 3：选择认证模式

```
? Authenticate Git with your GitHub credentials?
  Yes            # 使用 GitHub 凭证认证 Git 操作（推荐）
  No             # 手动配置 Git 凭证
```

通常选择 `Yes`，这样 `gh` 会自动配置 Git 凭证助手。
:::

::: details 步骤 4：选择登录方式

```
? How would you like to authenticate GitHub CLI?
  Login with a web browser    # 使用浏览器登录（推荐，最简单）
  Paste an authentication token  # 粘贴认证令牌
```

推荐选择 `Login with a web browser`，按回车后会生成一个一次性设备激活码。
:::

::: details 步骤 5：完成认证

1. 终端会显示类似这样的提示：

```
! First copy your one-time code: XXXX-XXXX
Press Enter to open github.com in your browser...
```

2. 按回车键，系统会自动打开默认浏览器（或手动复制设备激活码）

3. 在浏览器中：
   * 粘贴设备激活码
   * 点击 `Continue`
   * 在 GitHub 授权页面点击 `Authorize git` 完成授权

4. 回到终端，你会看到成功提示：

```
✓ Logged in as GitHub-username
✓ Configured Git credentials
```

:::

## 验证登录状态

登录完成后，可以使用以下命令验证是否成功：

```bash
gh auth status
```

输出示例：

```
github.com
  ✓ Logged in as <username>
  ✓ Git operations configured to use HTTPS protocol.
  ✓ Token: gho_************************************
  ✓ Token scopes: gist, read:org, repo, workflow
```

## 常用命令

登录成功后，你可以使用 `gh` 执行各种 GitHub 操作：

### 查看当前用户信息

```bash
gh api user
```

### 创建仓库

```bash
gh repo create my-repo --public --source=. --remote=origin --push
```

### 克隆仓库

```bash
gh repo clone owner/repo
```

### 查看 Issue

```bash
gh issue list
```

### 创建 Pull Request

```bash
gh pr create --title "Fix bug" --body "Fixed the critical bug"
```

### 查看 Pull Request 列表

```bash
gh pr list
```

### 查看 PR 详情

```bash
gh pr view 123
```

### 审查 PR

```bash
gh pr review 123 --approve
```

## 退出登录

如果需要退出 GitHub CLI 登录：

```bash
gh auth logout
```

## 配置 SSH 密钥（可选）

如果你选择使用 SSH 协议进行 Git 操作，可以使用 `gh` 快速配置 SSH 密钥：

### 上传现有 SSH 密钥

```bash
# 首先确保你有 SSH 密钥
ls ~/.ssh

# 上传到 GitHub
gh ssh-key add ~/.ssh/id_ed25519.pub --title "My MacBook"
```

### 生成新的 SSH 密钥并上传

```bash
# 生成新密钥
ssh-keygen -t ed25519 -C "your_email@example.com"

# 上传到 GitHub
gh ssh-key add ~/.ssh/id_ed25519.pub --title "My New Key"
```

### 查看 GitHub 上的 SSH 密钥

```bash
gh ssh-key list
```

### 删除 SSH 密钥

```bash
gh ssh-key delete <key-id>
```

## 环境变量配置

`gh` 支持通过环境变量进行配置：

```bash
# 设置默认的 GitHub 仓库
export GH_REPO=owner/repo

# 设置默认的 Git 协议
export GH_PROTOCOL=ssh

# 禁用自动更新提示
export GH_NO_UPDATE_NOTIFIER=1
```

将这些配置添加到你的 shell 配置文件（`~/.bashrc`、`~/.zshrc` 等）中使其永久生效。

::: tip 提示
你还可以创建配置文件 `~/.config/gh/config.yml` 进行更详细的配置：

```yaml
git_protocol: ssh
editor: vim
prompt: enabled
pager: less
```

:::

## 故障排查

### 问题：`gh: command not found`

**解决方案**：

1. 确认安装成功

```bash
# macOS
which gh

# Windows
where.exe gh
```

2. 如果没有输出，重新执行安装命令或手动安装

3. 刷新命令缓存

```bash
# bash/zsh
hash -r

# fish
rehash
```

### 问题：浏览器无法打开

**解决方案**：

手动复制设备激活码，在浏览器中访问 `https://github.com/login/device` 并输入激活码。

### 问题：认证失败

**解决方案**：

1. 确保网络连接正常
2. 检查是否使用了代理

```bash
# 如果使用代理，设置环境变量
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
```

3. 尝试清除缓存

```bash
gh auth logout
gh auth login
```

### 问题：权限不足

**解决方案**：

使用 `gh auth refresh` 刷新令牌权限：

```bash
gh auth refresh -h github.com -s admin:public_key,repo
```

### 问题：Token 过期

**解决方案**：

```bash
# 重新登录会自动刷新 token
gh auth login

# 或使用 refresh 命令
gh auth refresh
```

## 进阶技巧

### 多账户管理

如果你需要管理多个 GitHub 账户，可以使用 Git 配置：

```bash
# 为工作账户设置配置
git config --global credential.https://github.com.username work-user

# 或为特定仓库设置
cd ~/projects/work-repo
git config credential.https://github.com.username work-user
```

### 自动化脚本

在脚本中使用 `gh` 时，建议设置环境变量避免交互：

```bash
export GH_TOKEN=gho_xxxxxxxxxxxx
gh repo create test-repo --public
```

::: warning 安全提醒
不要将 `GH_TOKEN` 写入版本控制或日志文件中！建议使用环境变量或密钥管理工具。
:::

### 别名设置

为常用的 `gh` 命令设置别名以提高效率：

```bash
# 添加到 ~/.bashrc 或 ~/.zshrc
alias ghr='gh repo create'
alias ghpr='gh pr create'
alias ghi='gh issue create'
alias ghcl='gh repo clone'
```

## 总结

使用 GitHub CLI (`gh`) 登录 GitHub 的优势：

* ✅ **简单快捷**：通过浏览器一键授权，无需手动配置
* ✅ **安全性高**：使用 OAuth 2.0 认证，自动管理令牌
* ✅ **功能强大**：不仅用于登录，还可以执行各种 GitHub 操作
* ✅ **跨平台支持**：支持 macOS、Windows 和 Linux
* ✅ **脚本友好**：适合在自动化脚本中使用

::: info 参考资源

* [GitHub CLI 官方文档](https://cli.github.com/manual/)
* [GitHub CLI GitHub 仓库](https://github.com/cli/cli)
* [GitHub CLI 发布页](https://github.com/cli/cli/releases)
  :::