GitHub CLI 与 Codex 项目目录映射说明

1. 这次到底改了什么

这次不是改了 GitHub 官方的 gh.exe，也不是 GitHub CLI 原本自带了这个能力。

原始行为是：

gh pr status 默认依赖"当前目录是一个 Git 仓库"
它会先调用 git 判断当前仓库是谁
如果当前目录没有 .git，就会报错

典型报错就是：

text 复制代码

failed to run git: fatal: not a git repository

而 Codex 经常运行在这种目录里：

text 复制代码

C:\Users\你的用户名\Documents\Codex\某天\某个临时工作目录

这个目录通常不是 Git 仓库，所以 gh pr status 原生一定会失败。

2. 我是怎么做到的

我做的是一个 PowerShell 包装层，不是改 gh.exe 本体。

实现方式：

在 PowerShell profile 中加载一个自定义脚本
这个脚本定义了一个同名函数 gh
当你输入 gh ... 时，PowerShell 会先进入这个函数
这个函数只对 gh pr status 做额外处理
如果当前目录本身是 Git 仓库，就完全交给原始 gh.exe
如果当前目录不是 Git 仓库，就去查"项目目录 -> GitHub 仓库"的映射表
如果查到了映射，就自动补成：

powershell 复制代码

gh pr status -R owner/repo

如果没查到映射，就直接报错，不会偷偷选别的仓库

所以现在的规则是：

Git 仓库目录：按仓库本身查询
非 Git 仓库目录：按你手工配置的目录映射查询
没映射：报错

这符合"哪个项目就是哪个仓库"的要求。

3. 它原本就是这样设置的吗

不是。

GitHub CLI 原本没有"按本地任意目录映射仓库"的默认行为。

GitHub CLI 原生只支持这几类方式：

在真实 Git 仓库目录里运行
显式传 -R owner/repo
通过环境变量 GH_REPO 指定仓库

我现在加的是你本机自己的 PowerShell 扩展能力。

4. 当前机器上的关键文件

4.1 包装脚本

text 复制代码

C:\Users\ziyitty\Documents\Codex\2026-05-18\github-cli\scripts\GitHubCliFallback.ps1

4.2 PowerShell profile

text 复制代码

C:\Users\ziyitty\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1

profile 内容很简单，只负责加载脚本：

powershell 复制代码

$ghFallbackScript = "C:\Users\ziyitty\Documents\Codex\2026-05-18\github-cli\scripts\GitHubCliFallback.ps1"

if (Test-Path -LiteralPath $ghFallbackScript) {
    . $ghFallbackScript
}

4.3 目录映射配置文件

运行时会存到：

text 复制代码

%APPDATA%\GitHub CLI\codex-project-repos.json

在当前机器上通常是：

text 复制代码

C:\Users\ziyitty\AppData\Roaming\GitHub CLI\codex-project-repos.json

5. 日常怎么用

5.1 给某个项目目录绑定 GitHub 仓库

powershell 复制代码

Set-GhProjectRepo -ProjectPath 'C:\path\to\project' -Repository 'owner/repo'

例如：

powershell 复制代码

Set-GhProjectRepo -ProjectPath 'E:\UnityProject\yuanlin' -Repository 'your-org/your-repo'

5.2 查看当前所有映射

powershell 复制代码

Get-GhProjectRepoMap

5.3 删除一个项目映射

powershell 复制代码

Remove-GhProjectRepo -ProjectPath 'C:\path\to\project'

5.4 清空所有映射

powershell 复制代码

Clear-GhProjectRepoMap

5.5 使用 `gh pr status`

进入某个已映射目录后，直接执行：

powershell 复制代码

gh pr status

如果目录本身不是 Git 仓库，但映射存在，它会自动查对应 repo。

如果目录没映射，会报错提醒你先绑定。

6. 新机器如何从零设置

下面是最稳的做法。

步骤 1：安装 GitHub CLI

先确认新机器已经安装 gh：

powershell 复制代码

gh --version

如果没有安装，先安装 GitHub CLI。

步骤 2：登录 GitHub CLI

powershell 复制代码

gh auth login

登录后确认：

powershell 复制代码

gh auth status

步骤 3：拷贝包装脚本

把下面这个文件带到新机器某个固定位置：

text 复制代码

GitHubCliFallback.ps1

建议固定放到例如：

text 复制代码

C:\Tools\GitHubCliFallback.ps1

或者你自己的长期目录，不要放到一次性临时目录里。

原因：

PowerShell profile 里要引用这个脚本绝对路径
如果脚本放在会被清理的临时目录，之后会失效

步骤 4：配置 PowerShell profile

先看 profile 路径：

powershell 复制代码

$PROFILE

如果目录不存在就先创建：

powershell 复制代码

New-Item -ItemType Directory -Force -Path (Split-Path -Parent $PROFILE)

然后把下面内容写进去：

powershell 复制代码

$ghFallbackScript = "C:\Tools\GitHubCliFallback.ps1"

if (Test-Path -LiteralPath $ghFallbackScript) {
    . $ghFallbackScript
}

注意把路径改成你新机器上脚本的真实位置。

步骤 5：重新打开 PowerShell

关闭当前终端，重新打开 PowerShell。

然后验证函数是否加载成功：

powershell 复制代码

Get-Command gh
Get-Command Set-GhProjectRepo
Get-Command Get-GhProjectRepoMap

如果输出里能看到 Function，说明加载成功。

步骤 6：绑定你的项目目录

例如：

powershell 复制代码

Set-GhProjectRepo -ProjectPath 'E:\UnityProject\yuanlin' -Repository 'owner/repo'
Set-GhProjectRepo -ProjectPath 'E:\AI抠图' -Repository 'owner/another-repo'

步骤 7：验证

在非 Git 仓库目录中测试：

powershell 复制代码

cd C:\Users\你的用户名\Documents\Codex\some-folder
gh pr status

如果该目录没映射，应当报错。

在已映射目录中测试：

powershell 复制代码

cd E:\UnityProject\yuanlin
gh pr status

如果映射正确，应当返回该 repo 的 PR 状态。

7. 推荐的长期做法

建议你把脚本固定放在一个长期目录，而不是 Codex 的临时工作目录。

例如：

text 复制代码

C:\Tools\GitHubCliFallback.ps1

这样你换 Codex 会话目录、清理旧临时目录、或者迁移项目时，不会把这个功能一起删掉。

8. 如果你以后不想要这个功能

有两种撤销方式。

方式 1：只撤销目录映射

powershell 复制代码

Clear-GhProjectRepoMap

这会清掉映射，但保留 PowerShell 包装逻辑。

方式 2：彻底撤销

删除或清空 PowerShell profile 中加载脚本的那几行
删除 GitHubCliFallback.ps1
可选删除：

text 复制代码

%APPDATA%\GitHub CLI\codex-project-repos.json

这样系统就回到 GitHub CLI 原始行为。

9. 总结

一句话总结：

这不是 GitHub CLI 原生功能，而是我在 PowerShell 层加了一层"项目目录到 GitHub 仓库"的严格映射规则，让 Codex 在非 Git 仓库目录中也能按你定义的项目边界去查 PR 状态。

GitHub CLI 与 Codex 项目目录映射说明