g 安装与使用说明 #

1. g 是什么 #

g 是一个 Go 版本管理器，用来在一台机器上安装、切换、卸载多个 Go 版本。

它解决的核心问题有两个：

同一台机器需要同时维护多个 Go 版本。
项目依赖升级后，本机 Go 版本太旧，go build 直接失败。

g 的工作方式不是替换系统自带的 Go，而是把当前选中的版本链接到 ~\.g\go，再通过 PATH 让终端优先命中 ~\.g\go\bin\go.exe。

这意味着：

g use 1.24.13 只表示 g 已经把当前版本切到了 1.24.13。
真正执行 go version 时看到哪个版本，还取决于当前终端的 PATH 顺序。

2. g 的安装 #

本文档面向 Windows + PowerShell。

2.1 为什么这里不用一键安装脚本 #

这次实际安装过程中，g 的 install.ps1 在本机 Windows PowerShell 5.1 下报了解析错误，原因是脚本里用了较新的 PowerShell 语法。

因此，当前机器更稳的方案是：

手动下载 g 的 Windows amd64 发布包。
把 g.exe 放到 C:\Users\tianzhiwei\.g\bin\g.exe。

如果你用的是 PowerShell 7，可以再尝试官方脚本；如果还是 Windows PowerShell 5.1，建议直接走手动安装。

2.2 手动安装 g #

New-Item -ItemType Directory -Path "$HOME\.g\bin" -Force | Out-Null

打开 g 的 Release 页面，下载 Windows amd64 压缩包，解压后把 g.exe 放到：

C:\Users\tianzhiwei\.g\bin\g.exe

验证安装：

$env:Path = "$HOME\.g\bin;$env:Path"
g help

2.3 配置环境变量 #

建议把下面几个用户级环境变量设好：

[Environment]::SetEnvironmentVariable('G_HOME', "$HOME\.g", 'User')
[Environment]::SetEnvironmentVariable('G_MIRROR', 'official|https://golang.google.cn/dl/', 'User')
[Environment]::SetEnvironmentVariable('GOCACHE', "$HOME\.g\cache\go-build", 'User')

说明：

G_HOME：g 的工作目录。
G_MIRROR：Go 安装包下载镜像。
GOCACHE：Go 编译缓存目录。

2.4 配置 PowerShell 启动脚本 #

把下面内容写入 $PROFILE：

$env:G_HOME = "$HOME\.g"
$env:G_MIRROR = "official|https://golang.google.cn/dl/"
$env:GOCACHE = "$HOME\.g\cache\go-build"
$gPaths = @("$HOME\.g\bin", "$HOME\go\bin")

if (Test-Path "$HOME\.g\go\bin\go.exe") {
  $env:GOROOT = "$HOME\.g\go"
  $gPaths = @("$HOME\.g\bin", "$env:GOROOT\bin", "$HOME\go\bin")
}

$env:Path = (($gPaths + ($env:Path -split ';' | Where-Object { $_ -and ($gPaths -notcontains $_) })) -join ';')

作用：

把 ~\.g\bin 放到前面，保证 g 命令可用。
如果已经通过 g 安装了 Go，则把 ~\.g\go\bin 也放到前面。
让 go 优先命中 g 管理的版本，而不是 C:\Program Files\Go\bin\go.exe。

配置完成后执行：

. $PROFILE

或者直接关闭并重新打开 PowerShell。

2.5 安装 Go 版本 #

查看可安装版本：

g ls-remote stable
g ls-remote archived

安装指定版本：

g install 1.24.13

切换版本：

g use 1.24.13

验证：

g ls
where.exe go
go version

正常情况下：

g ls 中会看到 * 1.24.13
where.exe go 第一行应该是 C:\Users\tianzhiwei\.g\go\bin\go.exe
go version 应该输出 go version go1.24.13 windows/amd64

3. g 的常用命令 #

3.1 查看本地已安装版本 #

g ls

3.2 查看远端可安装版本 #

g ls-remote stable
g ls-remote archived
g ls-remote unstable

说明：

stable：当前仍受支持的稳定分支。
archived：历史版本和已退出主支持窗口的版本。
unstable：预发布版本。

3.3 安装版本 #

g install 1.25.8
g install 1.24.13

3.4 切换版本 #

g use 1.25.8
g use 1.24.13

3.5 查看 g 自身环境 #

g env

3.6 卸载版本 #

g uninstall 1.20.6

3.7 清理下载缓存 #

g clean

4. 踩坑记录 #

下面记录的是这次实际安装和排障过程中踩到的坑。

4.1 `g` 装好了，但 `go version` 还是旧版本 #

现象：

g ls
* 1.24.13

g use 1.24.13
Now using go1.24.13 windows/amd64

go version
go version go1.20.6 windows/amd64

原因：

g use 只切换了 g 的目标版本。
当前终端仍然优先命中了系统 Go：C:\Program Files\Go\bin\go.exe。

排查方法：

where.exe go
Get-Command go | Format-List Source

解决方式：

执行 . $PROFILE 重新加载 PowerShell 配置。
关闭当前终端，重新打开一个新的 PowerShell。
确保 where.exe go 的第一行是 C:\Users\tianzhiwei\.g\go\bin\go.exe。

补充：

如果你用的是 cmd、Git Bash、IDE 内置终端，它们不一定会加载 PowerShell 的 $PROFILE。
这种情况下，需要直接调整用户/系统 PATH，或者卸载旧的系统 Go。

4.2 `g ls-remote stable` 看不到 `1.24.13` #

现象：

g ls-remote stable

输出里只有两个主线版本，看不到 1.24.13。

原因：

截至 2026-03-13，1.24.x 已经不在 stable 列表里，而是在 archived 列表里。

解决方式：

g ls-remote archived
g install 1.24.13

结论：

找当前主支持版本，看 stable
找历史版本，看 archived

4.3 默认下载源不可用或不稳定 #

现象：

用 go.dev 时出现 TLS 握手超时。
某些镜像源虽然能打开网页，但 g 拉不到正确的版本索引。

这次验证下来，可用的配置是：

$env:G_MIRROR = "official|https://golang.google.cn/dl/"

建议同时持久化到用户环境变量。

4.4 `install.ps1` 在 Windows PowerShell 5.1 下报语法错误 #

现象：

运行 g 官方安装脚本时，PowerShell 直接报解析错误。

原因：

脚本里用了较新的 PowerShell 语法。
当前机器实际运行的是 Windows PowerShell 5.1，不是 PowerShell 7。

解决方式：

直接下载 release 包，手动放置 g.exe
或升级到 PowerShell 7 后再尝试脚本安装

4.5 `go build` 报缓存目录无权限 #

现象：

open C:\Users\tianzhiwei\AppData\Local\go-build\...\*: Access is denied

处理方式：

改用单独的 GOCACHE 目录。
本次配置中使用的是：

$env:GOCACHE = "$HOME\.g\cache\go-build"

如果这个目录也有权限问题，可以改成你确认可写的其他目录。

4.6 自动写 `$PROFILE` 时，变量提前展开会把配置写坏 #

这个坑主要出现在自动化脚本里。

现象：

本来只想把一段 PowerShell 片段写入 $PROFILE
结果 $env:Path、$env:GOROOT 等变量在写入时被提前展开
最终写进 profile 的不是脚本，而是一大段已经展开的字符串，导致 PowerShell 启动报错

解决方式：

手工编辑 $PROFILE 时，直接复制最终字面量内容
自动化写入时，优先使用单引号 here-string，避免变量被提前展开

5. 推荐排障顺序 #

如果你以后再遇到“g 已经切换，但 go 版本不对”的问题，按下面顺序排查即可：

g ls
where.exe go
go version
g env
. $PROFILE

判断标准：

g ls 看 * 指向的是不是目标版本
where.exe go 看第一行是不是 ~\.g\go\bin\go.exe
go version 看实际生效的是不是目标版本

如果 where.exe go 第一行仍然是 C:\Program Files\Go\bin\go.exe，问题就不在 g，而在 PATH 优先级。

g 安装与使用说明 #

1. g 是什么 #

2. g 的安装 #

2.1 为什么这里不用一键安装脚本 #

2.2 手动安装 g #

2.3 配置环境变量 #

2.4 配置 PowerShell 启动脚本 #

2.5 安装 Go 版本 #

3. g 的常用命令 #

3.1 查看本地已安装版本 #

3.2 查看远端可安装版本 #

3.3 安装版本 #

3.4 切换版本 #

3.5 查看 g 自身环境 #

3.6 卸载版本 #

3.7 清理下载缓存 #

4. 踩坑记录 #

4.1 g 装好了，但 go version 还是旧版本 #

4.2 g ls-remote stable 看不到 1.24.13 #

4.3 默认下载源不可用或不稳定 #

4.4 install.ps1 在 Windows PowerShell 5.1 下报语法错误 #

4.5 go build 报缓存目录无权限 #

4.6 自动写 $PROFILE 时，变量提前展开会把配置写坏 #

5. 推荐排障顺序 #

4.1 `g` 装好了，但 `go version` 还是旧版本 #

4.2 `g ls-remote stable` 看不到 `1.24.13` #

4.4 `install.ps1` 在 Windows PowerShell 5.1 下报语法错误 #

4.5 `go build` 报缓存目录无权限 #

4.6 自动写 `$PROFILE` 时，变量提前展开会把配置写坏 #