GitHub CLI 安装配置与核心命令实战指南

1. 为什么我劝你别再用网页版折腾 GitHub 了如果你日常跟代码打交道大概率经历过这样的场景在本地终端里改完代码想提个 PR结果得先切到浏览器打开 GitHub 网页点几下按钮填一堆表单再切回终端继续干活。来来回回切窗口思路断了好几次。更别提批量管理 Issue、查看 Actions 运行状态、克隆几十个仓库这种重复劳动网页端操作起来效率低得让人抓狂。GitHub CLI命令行工具命令名是gh就是来解决这个问题的。它把 GitHub 的核心操作——仓库管理、Issue、Pull Request、Actions、Release、Gist——全部搬到了终端里。你可以在命令行里直接创建仓库、提交 PR、查看 CI 状态、合并分支甚至调用 GitHub API。对于每天泡在终端里的开发者来说这东西一旦用上就回不去了。这篇内容适合三类人一是刚接触 GitHub CLI、不知道怎么装怎么配的新手二是装了但只用过gh auth login、没深挖过其他功能的中级用户三是想把这套工具集成到团队工作流里的技术负责人。我会从安装讲到配置从核心命令讲到实战场景把踩过的坑和总结的技巧都摊开说。不管你用的是 macOS、Windows 还是 Linux看完都能直接上手。2. 安装前的准备工作与方案选型2.1 先搞清楚你的系统环境和包管理器安装gh之前第一件事是确认你的操作系统和可用的包管理器。不同平台的安装方式差异很大选对了工具能省掉一堆麻烦。我见过不少人上来就手动下载二进制文件结果版本更新时又得重新折腾一遍完全没必要。先跑几个命令确认环境# 查看操作系统信息 uname -a # macOS 用户查看是否有 Homebrew brew --version # Windows 用户查看是否有 winget 或 scoop winget --version scoop --version # Linux 用户查看发行版 cat /etc/os-release确认清楚之后对照下面的表格选择最适合你的安装方式操作系统推荐方式备选方式自动更新macOSHomebrewMacPorts / 二进制包支持Windowswingetscoop / Chocolatey支持Debian/Ubuntuapt 官方源二进制包支持Fedora/RHELdnf 官方源二进制包支持Arch LinuxpacmanAUR支持其他 Linux二进制包源码编译手动提示优先选包管理器安装而不是手动下载二进制。包管理器帮你处理依赖、路径和更新手动装的话每次升级都得重新走一遍流程时间长了容易忘。2.2 为什么我不推荐用 npm 或 pip 装 gh网上有些教程会让你用npm install -g gh或者pip install gh来装我强烈不建议这么做。原因有三第一npm 和 pip 上的gh包很多是第三方封装的跟官方 GitHub CLI 不是一回事装完可能命令行为都对不上。第二即使找到了正确的包通过 Node 或 Python 运行时间接调用启动速度会慢一截而且多了一层运行时依赖出问题时排查链路变长。第三官方明确推荐用系统包管理器或官方源安装走非官方渠道遇到 bug 基本没人管。我早期图省事用 npm 装过一次结果gh pr create一直报认证错误折腾了半天才发现是包版本太旧跟服务端 API 不兼容。换成 Homebrew 重装后一次通过。这个坑希望大家别踩。2.3 版本选择稳定版还是尝鲜版GitHub CLI 的发布节奏比较快基本每个月都有小版本更新。官方提供稳定版stable和预发布版pre-release两个通道。除非你有明确需求要测试新功能否则一律选稳定版。预发布版虽然能提前用到新特性但偶尔会有回归问题生产环境千万别碰。查看当前最新稳定版版本号可以直接访问官方 Release 页面或者装完之后用gh --version确认。写这篇内容时稳定版已经在 2.x 系列如果你装出来还是 1.x说明源太旧了得换源。3. 各平台安装实操全流程3.1 macOS 上用 Homebrew 安装最省心macOS 用户是最幸福的Homebrew 一条命令搞定brew install gh如果你还没装 Homebrew先去官网按提示装好这里不展开。装完之后验证gh --version # 输出类似gh version 2.xx.x (2024-xx-xx)升级也很简单brew upgrade gh我一般会把升级命令写进一个每周执行的脚本里配合brew update一起跑省得手动记。Homebrew 装的好处是路径自动配好shell 补全也能通过brew的机制自动生效基本零配置。注意如果你用的是 Apple Silicon 芯片的 MacHomebrew 默认装在/opt/homebrew下Intel 芯片则在/usr/local。如果你之前从 Intel 机器迁移过配置可能会遇到路径冲突用which gh确认一下实际调用的二进制位置。3.2 Windows 上的三种装法对比Windows 平台稍微复杂一点因为有多个包管理器可选。我按推荐度排序winget首选Windows 10 1809 以上自带winget install --id GitHub.cliscoop次选适合喜欢干净隔离环境的用户scoop install ghChocolatey备选老牌包管理器但权限管理偶尔抽风choco install gh装完之后Windows 用户有个特殊注意点gh默认会调用系统配置的默认浏览器做 OAuth 认证。如果你用的是 WSL认证流程会稍微绕一点建议直接在 PowerShell 里完成认证再进 WSL 使用或者用 token 方式认证后面会讲。实测下来 winget 最稳升级用winget upgrade GitHub.cli即可。scoop 的好处是所有东西装在用户目录下不污染系统卸载干净。Chocolatey 我遇到过几次需要管理员权限才能升级的情况略烦。3.3 Linux 各发行版安装细节Linux 是gh的主场官方对主流发行版都有支持。Debian / Ubuntu走官方 apt 源# 添加官方 GPG key sudo mkdir -p -m 755 /etc/apt/keyrings wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg /dev/null sudo chmod gor /etc/apt/keyrings/githubcli-archive-keyring.gpg # 添加源 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/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 ghFedora / RHEL / CentOS用 dnfsudo dnf install dnf-command(config-manager) sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo sudo dnf install ghArch Linux最省事sudo pacman -S github-cli其他发行版或者没有 root 权限的情况直接下二进制包# 以 amd64 为例去 Release 页面找最新版本号替换 VERSION VERSION2.xx.x wget https://github.com/cli/cli/releases/download/v${VERSION}/gh_${VERSION}_linux_amd64.tar.gz tar -xzf gh_${VERSION}_linux_amd64.tar.gz sudo mv gh_${VERSION}_linux_amd64/bin/gh /usr/local/bin/二进制方式装完记得手动配 shell 补全否则 Tab 补全用不了体验差一大截。3.4 装完必做的验证与补全配置不管哪个平台装完先跑这三条命令确认状态gh --version # 确认版本 gh auth status # 确认认证状态此时应该提示未登录 gh config list # 查看当前配置然后配置 shell 补全。gh内置了补全生成命令非常方便# Bash gh completion -s bash | sudo tee /etc/bash_completion.d/gh /dev/null # Zsh gh completion -s zsh ${fpath[1]}/_gh # Fish gh completion -s fish ~/.config/fish/completions/gh.fish补全配好之后敲gh pr按 Tab 就能列出所有子命令效率提升非常明显。这一步很多人装完就忘了结果一直手敲完整命令白白浪费工具能力。4. 认证配置装完不配等于白装4.1 交互式登录的完整流程gh装完第一件事就是认证否则所有需要访问 GitHub 的命令都会失败。最常用的方式是交互式登录gh auth login它会依次问你几个问题What account do you want to log into?选 GitHub.com除非你用企业版What is your preferred protocol for Git operations?选 HTTPS 或 SSHAuthenticate Git with your GitHub credentials?选 YesHow would you like to authenticate?选 Login with a web browser然后它会显示一个一次性验证码并提示你按回车打开浏览器。在浏览器里输入验证码、授权回到终端就完成了。提示如果你在无图形界面的服务器上操作浏览器打不开这时候选 Paste an authentication token 方式提前在网页端生成一个 Personal Access Token 粘进去即可。4.2 Token 认证适合服务器和 CI 环境服务器、容器、CI 流水线里没法开浏览器这时候用 Token 认证# 方式一通过环境变量 export GH_TOKENghp_xxxxxxxxxxxxxxxxxxxx gh auth status # 方式二通过标准输入 echo ghp_xxxxxxxxxxxxxxxxxxxx | gh auth login --with-tokenToken 的权限范围要按需给。如果只是读仓库repo和read:org就够了如果要操作 Actions得加上workflow。权限给多了有安全风险给少了命令跑不通这个平衡要把握好。我个人的习惯是本地开发机用交互式登录服务器和 CI 用细粒度 Token并且定期轮换。Token 千万别硬编码在脚本里提交到仓库用环境变量或密钥管理服务注入。4.3 多账号切换的实用技巧很多人有多个 GitHub 账号——公司一个、个人一个。gh支持多账号管理但切换逻辑跟 Git 本身的配置是分开的这点容易搞混。# 查看所有已登录账号 gh auth status # 切换活跃账号 gh auth switch # 指定账号执行某条命令 gh auth switch --user work-account关键点在于gh的账号切换只影响gh自己的命令不影响git push用的凭据。如果你想让git也跟着切得配合gh auth setup-git重新配置或者手动管理 SSH key。我踩过的坑是切了gh账号但git push还是推到旧账号的仓库排查半天才发现是两套体系。5. 核心命令实战从建仓库到提 PR5.1 仓库操作创建、克隆、Forkgh最常用的就是仓库相关操作。创建新仓库# 在当前目录初始化并创建远程仓库 gh repo create my-project --public --source. --push # 只创建远程仓库不关联本地 gh repo create my-project --private--source.表示用当前目录作为源--push表示创建完直接推上去。这一条命令顶网页端好几步操作。克隆仓库时gh比git clone多了个便利可以直接用owner/repo简写不用敲完整 URLgh repo clone cli/cli gh repo clone cli/cli my-local-name # 指定本地目录名Fork 也很方便gh repo fork cli/cli --clonetrue--clonetrue表示 fork 完自动克隆到本地省得再手动 clone 一次。5.2 Issue 与 PR 的终端化管理查看和创建 Issue# 列出当前仓库的 open issue gh issue list # 按标签过滤 gh issue list --label bug --state open # 创建 issue gh issue create --title 登录页面报错 --body 复现步骤... --label bugPR 操作是重头戏# 从当前分支创建 PR gh pr create --title 修复登录逻辑 --body 改动说明... --base main # 交互式创建会引导你填标题和描述 gh pr create # 查看 PR 列表和详情 gh pr list gh pr view 123 # 检出别人的 PR 到本地 gh pr checkout 123 # 查看 PR 的 CI 状态 gh pr checks 123 # 合并 PR gh pr merge 123 --squash --delete-branchgh pr checkout这个命令我几乎每天都在用。以前 review 别人的 PR 得先git fetch再切分支现在一条命令搞定而且会自动配好 upstream 跟踪。5.3 Actions 与 Release 的快捷操作查看工作流运行状态# 列出最近的运行 gh run list # 查看某次运行的详情 gh run view run-id # 实时跟踪运行日志 gh run watch run-id # 重新触发失败的任务 gh run rerun run-id --failedRelease 管理# 创建 release 并上传产物 gh release create v1.0.0 ./dist/*.tar.gz --title v1.0.0 --notes 首个正式版 # 下载 release 产物 gh release download v1.0.0这些命令在 CI 脚本里特别有用。比如自动发布流程里用gh release create一步完成打标签、写说明、传产物比调 API 简单太多。6. 常见问题排查与避坑经验6.1 认证类问题速查现象可能原因解决方法gh: not logged in未认证或 token 过期重新gh auth loginHTTP 401Token 权限不足或失效检查 token scope重新生成HTTP 403触发速率限制等待或换 token浏览器认证卡住无图形界面或端口被占改用 token 认证多账号串号gh 与 git 凭据不同步gh auth setup-git重配6.2 网络与代理相关排查企业内网环境经常遇到连接问题。gh会读取HTTPS_PROXY和HTTP_PROXY环境变量如果公司有代理提前配好export HTTPS_PROXYhttp://proxy.company.com:8080 export HTTP_PROXYhttp://proxy.company.com:8080如果配了代理还是连不上用gh auth status --show-token看详细错误或者加GH_DEBUGapi打印请求日志定位是 DNS 问题还是证书问题。我遇到过公司自签证书导致 TLS 握手失败的情况解决办法是把公司根证书导入系统信任链而不是关掉证书校验关校验有安全风险别干。6.3 版本冲突与路径问题如果你之前手动装过gh后来又用包管理器装了一遍可能出现which gh指向旧版本的情况。排查步骤which -a gh # 列出所有 gh 路径 echo $PATH # 看路径优先级把旧版本的二进制删掉或者调整 PATH 顺序。macOS 上常见的是/usr/local/bin/gh和/opt/homebrew/bin/gh打架统一用一个就行。提示升级gh之后如果命令行为异常先跑gh config list看看配置有没有被旧版本残留污染必要时清掉~/.config/gh/重新认证。7. 把 gh 用进日常工作流的几点心得装了gh只是第一步真正提升效率的是把它嵌进日常流程。我自己的做法是写几个 alias 和 shell 函数把高频操作封装起来。比如# 一键创建 PR 并请求 review alias prcgh pr create --fill gh pr view --web # 快速切到某个 PR gpr() { gh pr checkout $1; } # 查看我负责的待 review PR alias myreviewgh pr list --search review-requested:me--fill这个参数很实用它会自动用 commit 信息填充 PR 标题和描述省得手敲。配合--web直接在浏览器打开确认流程很顺。另外gh api是个被低估的命令它能直接调 GitHub REST API返回 JSON 可以用jq处理。比如批量导出仓库列表、统计贡献数据都能用它搞定。我写过一个小脚本用gh api拉取所有仓库的 star 数做排序比网页端一个个看快多了。最后提醒一句gh的配置存在~/.config/gh/config.yml里面可以设默认编辑器、默认协议、别名等。花十分钟把配置文件过一遍按自己习惯调好长期收益很大。我个人的配置里设了默认编辑器为 vim、默认协议为 ssh、加了几个常用别名用起来顺手不少。