企业官网建设流程全解析

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

确认清楚之后，对照下面的表格选择最适合你的安装方式：

提示：优先选包管理器安装，而不是手动下载二进制。包管理器帮你处理依赖、路径和更新，手动装的话每次升级都得重新走一遍流程，时间长了容易忘。

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 芯片的 Mac，Homebrew 默认装在/opt/homebrew下，Intel 芯片则在/usr/local。如果你之前从 Intel 机器迁移过配置，可能会遇到路径冲突，用which gh确认一下实际调用的二进制位置。

3.2 Windows 上的三种装法对比

Windows 平台稍微复杂一点，因为有多个包管理器可选。我按推荐度排序：

winget（首选），Windows 10 1809 以上自带：

winget install --id GitHub.cli

scoop（次选），适合喜欢干净隔离环境的用户：

scoop install gh

Chocolatey（备选），老牌包管理器，但权限管理偶尔抽风：

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 go+r /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 gh

Fedora / RHEL / CentOS用 dnf：

sudo dnf install 'dnf-command(config-manager)' sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo sudo dnf install gh

Arch Linux最省事：

sudo pacman -S github-cli

其他发行版或者没有 root 权限的情况，直接下二进制包：

# 以 amd64 为例，去 Release 页面找最新版本号替换 VERSION VERSION=2.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

它会依次问你几个问题：

1. What account do you want to log into?选 GitHub.com（除非你用企业版）
2. What is your preferred protocol for Git operations?选 HTTPS 或 SSH
3. Authenticate Git with your GitHub credentials?选 Yes
4. How 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_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx gh auth status # 方式二：通过标准输入 echo "ghp_xxxxxxxxxxxxxxxxxxxx" | gh auth login --with-token

Token 的权限范围要按需给。如果只是读仓库，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. 核心命令实战：从建仓库到提 PR

5.1 仓库操作：创建、克隆、Fork

gh最常用的就是仓库相关操作。创建新仓库：

# 在当前目录初始化并创建远程仓库 gh repo create my-project --public --source=. --push # 只创建远程仓库，不关联本地 gh repo create my-project --private

--source=.表示用当前目录作为源，--push表示创建完直接推上去。这一条命令顶网页端好几步操作。

克隆仓库时，gh比git clone多了个便利：可以直接用owner/repo简写，不用敲完整 URL：

gh repo clone cli/cli gh repo clone cli/cli my-local-name # 指定本地目录名

Fork 也很方便：

gh repo fork cli/cli --clone=true

--clone=true表示 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 bug

PR 操作是重头戏：

# 从当前分支创建 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-branch

gh 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> --failed

Release 管理：

# 创建 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 认证类问题速查

6.2 网络与代理相关排查

企业内网环境经常遇到连接问题。gh会读取HTTPS_PROXY和HTTP_PROXY环境变量，如果公司有代理，提前配好：

export HTTPS_PROXY=http://proxy.company.com:8080 export HTTP_PROXY=http://proxy.company.com:8080

如果配了代理还是连不上，用gh auth status --show-token看详细错误，或者加GH_DEBUG=api打印请求日志，定位是 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 prc='gh pr create --fill && gh pr view --web' # 快速切到某个 PR gpr() { gh pr checkout "$1"; } # 查看我负责的待 review PR alias myreview='gh 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、加了几个常用别名，用起来顺手不少。