MacOS 手动安装 GitHub CLI(gh) + CI/CD 实时监控（实测：国内网络适配）

MacOS 手动安装 GitHub CLI(gh) + CI/CD 实时监控（实测：国内网络适配）

前言

在开发过程中，GitHub Actions CI/CD 流水线是保障代码质量的核心，但国内网络环境下存在3大痛点：

本教程基于 Mac M系列芯片（Apple Silicon），采用手动下载安装 + Token最小权限登录方案，100%规避网络问题，实现 CI 流水线实时监控、完整日志查看、一键自动化开发。

一、环境说明

• 系统：macOS
• 终端：zsh（Mac 默认终端）
• 核心工具：GitHub CLI (gh)
• 用途：监控 GitHub Actions CI/CD、查看完整错误日志、自动化开发推送流程

二、手动下载安装 GitHub CLI（国内网络专用，彻底避开brew超时）

1. 浏览器下载安装包

打开官方下载地址，选择 macOS ARM64 版本：

官方下载：https://github.com/cli/cli/releases/latest 下载文件：gh_xxx_macOS_arm64.tar.gz

下载完成后，解压得到文件夹，默认保存在系统「下载/Downloads」目录。

2. 执行安装命令

打开终端，逐行复制运行：

# 创建用户工具存放目录
mkdir -p ~/.local/bin

# 自动匹配下载的gh版本，无需手动修改版本号
cp ~/Downloads/gh_*_macOS_arm64/bin/gh ~/.local/bin/gh

# 赋予gh可执行权限
chmod +x ~/.local/bin/gh

3. 配置环境变量（永久生效，全局可用gh命令）

# 将工具目录加入系统环境变量
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# 刷新终端配置，立即生效
source ~/.zshrc

4. 验证安装成功

gh –version

✅ 输出版本号（如 gh version 2.92.0）即安装成功！

三、生成 GitHub Personal Access Token（最小权限原则·安全优先）

⚠️ 重要提醒：Token等价于你的GitHub密码，禁止截图分享、禁止提交到代码仓库，建议存入密钥管理工具（1Password等）

1. 打开Token创建页面

https://github.com/settings/tokens?type=beta

2. 核心安全配置（仅开启必要权限，避免全仓库授权风险）

3. 复制Token

生成后会得到一串以 github_ 开头的令牌（仅显示一次，务必保存） 示例（打码）：github_************************************

四、GitHub CLI 登录（令牌登录，彻底解决网络超时）

1. 执行登录命令

gh auth login

2. 按步骤选择配置（全程回车+选择，无脑操作）

3. 粘贴Token完成登录

终端提示：? Paste your authentication token: 粘贴你生成的Token → 回车

✅ 登录成功提示：

✓ Configured git protocol
✓ Logged in as xxxxx（你的GitHub用户名）

五、GitHub Actions CI/CD 核心命令（开发必备，直接复制）

前置验证：确认当前处于正确的项目仓库目录

# 查看当前仓库信息，避免在错误目录执行命令
gh repo view

1. 实时监控最新CI流水线（最常用）

代码推送后，自动等待CI执行完成，失败自动高亮报错

gh run watch

2. 查看最近5条CI运行记录

gh run list –limit 5

3. 查看上一次失败的完整错误日志（定位Bug神器）

gh run view –last-failed –log

4. 查看指定CI任务的完整日志

gh run view 任务ID –log

5. 网络不稳定时，配置临时代理（可选）

自备代理后，执行以下命令临时加速gh网络请求

# 端口根据你的实际代理端口修改
export https_proxy=http://127.0.0.1:7890
gh run watch

六、一键自动化脚本（错误中断保护·开发效率拉满）

将 代码提交 → 推送 → 监控CI 合并为一条命令，加入错误中断逻辑，避免推送失败后无效执行监控命令

💡 提醒：git add . 会添加目录下所有文件，请提前配置好.gitignore忽略不需要提交的文件

# 开启错误中断：任意命令执行失败，立即终止后续流程
set -e
git add .
git commit -m "feat: 业务功能开发"
git push
gh run watch

七、常见问题排查（零踩坑指南）

问题1：zsh: command not found: gh

原因：环境变量未生效 解决方案：重新执行环境变量配置

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

问题2：登录时网络超时

原因：国内网络无法连接GitHub网页授权接口 解决方案：必须使用Token登录，放弃浏览器授权方式

问题3：无法查看CI完整日志

原因：Token权限缺失Workflows读权限 解决方案：重新生成Token，务必勾选Workflows读权限

问题4：gh命令执行超时

原因：GitHub服务器访问不稳定 解决方案：配置代理后执行，或等待网络稳定重试

问题5：手动安装gh无法自动更新

说明：手动安装方式无自动更新机制 解决方案：每季度访问 gh Releases页面 检查新版本，重复本教程安装步骤即可升级

八、教程总结

本教程通过 「手动安装gh + Token最小权限登录 + 错误中断自动化脚本」 三件套，100%规避国内网络环境下GitHub CLI的使用痛点：

配置一次，长期受益，可大幅降低上线前的代码Bug率，适合日常开发CI/CD流程规范化落地。