GitHub CLI 怎么创建带参数的命令别名

GitHub CLI 创建带参数的命令别名，核心是用 gh alias set 保存展开式，并用 $1、$2 接收调用时传入的位置参数。例如执行 gh alias set prw 'pr view "$1" --web' 后，输入 gh prw 128，就会展开为 gh pr view 128 --web。单条 gh 命令使用普通别名即可；涉及管道、重定向或多条 shell 命令时，再使用 --shell。

官方手册：https://cli.github.com/manual/gh_alias_set

先选对别名类型

步骤一：确认 GitHub CLI 可以使用

命令入口：gh --version → gh auth status。先确认本机能够找到 gh，再确认当前主机已经完成认证。

# 确认 GitHub CLI 已安装，并查看当前版本。
gh --version

# 检查当前认证状态，避免别名创建后因未登录而调用失败。
gh auth status

成功标志：第一条命令输出版本号，第二条命令显示已登录的 GitHub 主机与认证状态。别名本身可以在未进入仓库目录时创建，但执行某些仓库相关命令时仍需处于可识别的仓库环境，或显式提供仓库参数。

步骤二：创建接收一个参数的普通别名

命令路径：gh alias set；参数位置：别名名称 → 展开式。下面把 prw 定义为“按编号打开 PR 页面”。

# 单引号保护 $1，避免当前 shell 在保存别名前提前展开它。
gh alias set prw 'pr view "$1" --web'

# 传入 PR 编号；$1 会在调用时替换为 128。
gh prw 128

这里的 prw 是别名名称，pr view "$1" --web 是展开式。执行 gh prw 128 时，位置参数 $1 被替换为 128。普通别名的展开式不需要再次写开头的 gh。

成功标志：创建命令返回别名已添加的信息；运行 gh prw 128 后，CLI 按 gh pr view 128 --web 的含义执行。如果展开式里没有 $1、$2 等占位符，调用时额外输入的参数会自动追加到展开式末尾。

步骤三：创建接收多个参数的 Shell 别名

需要管道时不能只保存普通子命令，应使用 --shell。下面的 igrep 接收两个参数：$1 是 Issue 标签，$2 是要过滤的关键词。为了减少多层引号冲突，展开式从标准输入读取。

# printf 把完整展开式送入标准输入，末尾的 - 表示从标准输入读取。
printf '%s\n' 'gh issue list --label="$1" | grep "$2"' \
  | gh alias set --shell igrep -

# 第一个参数是标签，第二个参数是要匹配的关键词。
gh igrep bug timeout

成功标志：执行 gh igrep bug timeout 后，先列出带有 bug 标签的 Issue，再仅保留包含 timeout 的行。Shell 别名由 sh 解释，应始终给位置参数加引号，并避免把来源不可信的文本直接拼入可执行结构。

步骤四：列出别名并核对参数展开

检查路径：gh alias list。该命令也有简写别名 gh alias ls。创建后先查看保存结果，再用无破坏性的测试参数运行一次。

# 列出所有已保存的别名，检查名称和展开式。
gh alias list

# 使用测试编号核对 $1 的替换结果。
gh prw 128

成功标志：gh alias list 中能看到 prw 与 igrep，测试调用的参数顺序与预期一致。若命令执行失败，先判断问题来自别名展开、认证状态、当前仓库，还是目标资源本身。

步骤五：覆盖更新或删除别名

同名别名默认不会被静默替换。确认要修改后，通过 --clobber 覆盖；不再使用时，通过 gh alias delete 删除指定名称。

# --clobber 明确覆盖同名别名，把行为改为查看 PR 评论。
gh alias set --clobber prw 'pr view "$1" --comments'

# 删除不再使用的单个别名，避免误删其他配置。
gh alias delete prw

成功标志：覆盖后，gh alias list 显示新的展开式；删除后，列表中不再出现该名称。gh alias delete --all 会删除全部别名，只有在确认无需保留任何现有配置时才应使用。

Windows 下如何减少引号问题

GitHub CLI 官方手册特别说明：Windows Command Prompt 中设置包含参数的展开式时需要使用双引号。PowerShell、Command Prompt 与类 Unix shell 的变量和引号规则不同，直接复制复杂命令可能导致 $1 被提前处理。

更稳妥的办法是使用本教程步骤三的“标准输入 + -”方案：先让当前 shell 生成完整展开式，再交给 gh alias set ... - 保存。保存后立即执行 gh alias list，以实际列表内容为准核对占位符是否仍然存在。

常见问题排查

1. 提示别名已经存在

这是防止误覆盖的正常行为。先运行 gh alias list 查看旧定义；确认要替换后，再添加 --clobber。

2. 列表里的 $1 变成了空字符串

通常是外层 shell 在保存时提前展开了变量。类 Unix shell 中优先用单引号包住展开式，或者通过标准输入传入；不要在未转义的双引号里直接写 $1。

3. 管道符被当成普通字符

普通别名不会按完整 shell 表达式执行。涉及 |、>、条件判断或多条命令时，使用 --shell，也可以让展开式以 ! 开头表示 Shell 别名。

4. 多传了参数，为什么它出现在命令末尾

当展开式没有位置占位符时，GitHub CLI 会把调用别名时提供的额外参数追加到展开式末尾。如果需要固定参数位置，请显式使用 $1、$2。

5. 别名存在，但执行时找不到 PR 或 Issue

别名只负责展开命令，不会改变仓库上下文或权限。检查当前目录对应的仓库、登录主机、资源编号和访问权限；需要跨仓库运行时，可在原命令支持的情况下补充仓库选项。

推荐的最小操作闭环

1. 用单引号或标准输入保护 $1、$2。
2. 单条 gh 子命令使用普通别名，管道与重定向使用 --shell。
3. 创建后立即运行 gh alias list，确认占位符和引号都被正确保存。
4. 用无破坏性的测试参数执行一次，确认参数顺序。
5. 修改时用 --clobber，废弃时只删除指定别名。

按这套方法配置后，常用 GitHub CLI 工作流可以压缩成短命令，同时仍然保留清晰的参数入口。最重要的判断只有两个：参数是否需要固定位置，以及展开式是否需要 shell 能力。