装完 Go 的第一天,我卡在 GOPATH 上

难度 ★☆☆☆☆ · 前置:无 | 一句话结论:GOROOT 指 Go 自己装在哪,GOPATH 指你的东西放哪,GOBIN 指编译出来的可执行文件落哪。三个地址各管一件事,混起来就会把找不到命令和找不到包当成同一个错。

装 Go 那天我干的事很少,下载 msi,一路下一步,装完打开终端敲 go version,屏幕上回了 go1.21.0 windows/amd64,我当时觉得这事就完了,前后不到五分钟。然后我建了个文件夹,写了个 main.go,照着教程敲 go run main.go,报错,不是那种看不懂的报错,是那种看上去特别理直气壮、让你怀疑自己是不是漏了一步的报错,go: go.mod file not found in current directory or any parent directory; see 'go help modules'。我盯着这行字看了半天,第一反应是安装没装全,于是卸载、重装、重启终端,再来一次,还是这行。第二反应是教程过时了,去翻官网,官网的例子能跑,因为人家给了完整目录,我缺的那一步在教程里被当作常识省掉了。

我大概花了一个晚上才明白,这行报错跟装没装好一点关系都没有,它说的是一件完全不同的事,它说的是我不知道这个项目属于谁。那一个晚上我先后怀疑了安装包不完整、怀疑了系统权限、怀疑了杀毒软件拦截,唯独没有怀疑自己少理解了一个概念,而报错信息其实在第一行就告诉我该去看哪一页了,只是我当时不认识那行字的价值,直接把它当成失败的证据划过去了。

这件事我一直记得。

从那以后我养成了一个习惯,看到报错里带 see 'go help xxx' 这种指引就当命令执行,去把那页文档翻完,绝大多数情况下答案就在里面,不用去搜论坛,也不用怀疑自己电脑有问题。

三个地址,三件事

第一步是先认名字。

Go 装完之后会留三个地址,这三个地址对应三个环境变量,名字都长得差不多,都带 G,都以 PATH 结尾或者曾经以 PATH 结尾,所以特别容易糊成一团。我当时的直觉是它们层层包含,GOPATH 应该是 GOROOT 下面的某个子目录,因为它俩名字太像了,像到我觉得后者是前者的扩展,这个错误直觉害我在后面排查路径问题时多绕了两圈。

变量 指向什么 谁来定
GOROOT Go 自己装在哪,标准库源码和编译器都在这下面 安装包自动填,一般不用动
GOPATH 你的工作区,第三方依赖缓存和 go install 的产物都往这走 装完有个默认值,可以改
GOBIN go install 出来的可执行文件放哪 默认空,空了就用 GOPATH/bin

实际跑一下就看出来了,这两个根根本不在一个地方,本机上一个是 D:\Go,另一个是 C:\Users\Devil\AppData\Local\Temp\gopath,一个在 D 盘一个在 C 盘,中间没有任何包含关系,它们是平行的两个根,一个放语言本身,一个放你写的东西,谁也不在谁里面,把它们想成一个大文件夹套一个小文件夹,从一开始方向就错了。

1
go env GOROOT GOPATH GOBIN GOMODCACHE GOCACHE
1
2
3
4
5
D:\Go
C:\Users\Devil\AppData\Local\Temp/gopath
D:\Go\bin
C:\Users\Devil\AppData\Local\Temp/gomod
C:\Users\Devil\AppData\Local\Temp/gocache

这台机器上 GOBIN 显示成了 D:\Go\bin,看着像是安装包填的,其实不是,是我自己用 go env -w 写进去的,这一条后面单独说,它坑过我一次。

GOROOT 是 Go 自己的住址

GOROOT 下面有三样东西,值得 ls 一遍,因为后面所有的实验都建立在这上面的东西能跑通,你至少得知道自己 C 盘或者 D 盘上凭空多了几万个文件是干什么用的。

1
2
3
4
5
D:\Go
├── bin go.exe、gofmt.exe
├── pkg
│ └── tool compile、link、asm 这些真正干活的小工具
└── src fmt、runtime、net 这些标准库的源码

src 那个目录是全专栏最值钱的东西。

fmt、runtime、sync 的源码全在里面,写到后面讲调度器、讲 GC 的时候,你要看的 runtime/proc.go、runtime/mgc.go 就在 D:\Go\src\runtime\ 下面,不需要去 GitHub 上翻,也不需要 clone 仓库,而且本机这份和你正在跑的二进制是同一个版本,不会出现文档对不上源码的情况。这一点在排查版本相关的问题时特别关键,你在网上搜到的实现可能是三年前的,本机这份永远准。

pkg/tool 里那一堆小工具平时看不见,go build 在背后挨个调它们,-x 参数能把这条命令链打出来,前几行长这样。

1
go build -x . 2>&1 | head -5
1
2
3
mkdir -p $WORK\b015\
mkdir -p $WORK\b006\
mkdir -p $WORK\b014\

$WORK 是每次编译现开的临时目录,编完就删,所以你在里面找不到任何想留着的东西。

GOROOT 一般不用改,改了反而危险,因为标准库的路径是按它算的,指错了连 fmt 都找不到。有一类情况你确实会碰到它,装了多个版本的 Go,想切着用,这时候正确的做法是改 PATH 里 go.exe 的优先级,或者用 go install golang.org/dl/go1.22.0@latest 装个版本管理器,而不是去改 GOROOT。

GOPATH 曾经是整个世界

这一节要讲点历史,因为不讲历史就理解不了 GOPATH 现在为什么长这个样子。

2018 年模块模式之前,Go 只有一种组织代码的方式,所有代码都必须放在 $GOPATH/src 下面,而且目录结构必须和导入路径一模一样。你要用 github.com/pkg/errors,那个包就必须位于 $GOPATH/src/github.com/pkg/errors,一个字都不能差,go get 干的事就是按导入路径算出一个目标目录,然后 git clone 到那儿。这套规则的好处是极简,路径就是身份,不用任何配置文件就能确定一个包在哪,坏处是极不自由,你的项目不能放在自己想放的地方,git clone 一个项目下来,如果它在 /home/me/work/foo,你必须把它移进 $GOPATH/src/github.com/someone/foo 才能编译。而且所有人共用一份 GOPATH,两个项目要同一个库的两个版本,没辙,这个问题在 2016 年之前靠 vendor 目录勉强绕着走,每份代码里塞一份依赖副本,仓库大得离谱,现在回头看那几年,整个生态都在为一条路径规则买单。语言核心团队当时讨论过好几种方案,包括给每个项目一个独立的 GOPATH、用子目录当版本号、把版本信息塞进导入路径,最后选的那条路最笨也最结实,就是在项目根目录放一个文本文件,把依赖和版本写死在里面,编译时按这个文件去缓存里找,这个文件就是 go.mod,模块这个词从此有了第二个意思。

模块模式把这些全解掉了,项目可以放在任何地方,版本写在文件里,但 GOPATH 这个变量没被删掉,它退化成了别的东西。

现在的 GOPATH 只负责三件事。

子目录 放什么 能不能随便删
pkg/mod 下载下来的第三方模块,按版本分目录 能,重下就行
bin go install 装的可执行文件 能,重装就行
src 模块模式下基本不用了,空着很正常 能

src 空着是正常的。

我第一次看到自己的 GOPATH 下面只有 pkg 和 bin、没有 src,还专门 mkdir 了一个,以为缺了什么。其实不用建,模块模式根本不看它。

真正天天打交道的其实是 pkg/mod,也就是 GOMODCACHE 指向的地方。你 go get 一个库,它落在 $GOMODCACHE/github.com/pkg/errors@v0.9.1/ 这种路径下,目录名里带版本号,所以同一个库的多个版本可以并存,这正是老 GOPATH 做不到的事,也是模块模式最实在的那部分收益。缓存里还有一份 cache/download,存的是原始 zip 和校验文件,go mod tidy 断网时能救急的就是它,删了这个目录,下次构建就得重新下一遍,所以清理磁盘的时候要认准,删 pkg/mod 没问题,删 pkg/mod/cache/download 只是下次慢一点,而删 GOPATH 整个目录本身,你装的那些命令行工具会一起没了,得重新 go install 一遍。这块缓存会一直长,我这台机器上装了不到二十个项目,pkg/mod 已经三五百兆,因为它按模块加版本存,同一个库的 v0.8.1 和 v0.9.1 是两份完整副本,谁也不会替你合并,也没有任何清理机制,只有你自己知道哪个项目早就删了、它用过的版本再也不会碰。

GOROOT、GOPATH、项目目录三个容器各放什么

GOBIN 那一下,我找了半小时

go install 装出来的二进制去哪,答案是 GOBIN,没有就 GOPATH/bin,这句话我在文档里读到过至少三遍,但真到自己机器上还是懵了半小时。因为这台机器的 GOBIN 不是空的,我在 $GOPATH/src 下面建了个小工具,go install ./cmd/hello,装完去 $GOPATH/bin 找,没有,那个目录压根不存在。我以为装失败了,重装,还是没报错,还是找不到文件,最后是 where hello 找到的。

1
where hello
1
D:\Go\bin\hello.exe

原因写在 C:\Users\Devil\AppData\Roaming\go\env 这个文件里,那是我很久以前跑 go env -w GOBIN=D:\Go\bin 留下的记录,go env -w 不是改当前终端,是把配置写进这个文件,永久生效,换终端、重启都没用。

1
2
go env -w GOBIN=D:\Go\bin
go env -w GOSUMDB=off

这两条命令本身没错,但它们有个副作用,你会在半年后忘记自己写过。go env 输出的每一项都能被三层覆盖,最底下是默认值,中间是 go env -w 写进配置文件的值,最上面是当前 shell 的 export,一层压一层,而 go env -w 那层看不见摸不着,比 shell 变量难查得多,搜报错也搜不到,因为它根本不在报错信息里出现。

清掉的办法是 go env -u GOBIN,不是 rm 那个文件,那个文件里还存着别的设置,删了会连带丢掉。

现在回头看,GOBIN 设成 D:\Go\bin 这件事本身就不太对,那地方是 Go 自己的目录,卸载重装 Go 会被一起清掉,你自己装的一堆工具跟着没了。让它留空,让 go install 老老实实往 GOPATH/bin 里放,然后把 GOPATH/bin 加进 PATH,这才是能活过重装的做法,实测把 GOENV 文件挪走之后,GOBIN 立刻回落到 C:\Users\Devil\AppData\Local\Temp\gopath\bin 这个默认位置,验证起来很快,一条命令的事。

两句报错,两个病根

command not found 和 cannot find package 差得很远,但新手特别容易混,因为两句都带找不到三个字,都出现在你以为万事俱备的时候。

第一句是 shell 说的,不是 Go 说的。

你在终端敲了一个名字,shell 去 PATH 列的那一串目录里挨个找,一个都没找着,就回你 bash: nope-go: command not found。这说明你要执行的程序不在 PATH 里,跟 Go 一点关系都没有,装没装 Go 都可能出现,docker、node、你自己写的脚本全都会这么报。

第二句是 Go 说的,它出现在老式的 GO111MODULE=off 模式下,你 import 了一个本地没有的包。

1
GO111MODULE=off go build .
1
2
3
main.go:3:8: cannot find package "github.com/nonexistent/pkg" in any of:
D:\Go\src\github.com\nonexistent\pkg (from $GOROOT)
C:\Users\Devil\AppData\Local\Temp\gopath\src\github.com\nonexistent\pkg (from $GOPATH)

这行输出信息量很大,它把找过的每个地方都列出来了,而且标了这块是从哪个变量算来的,from $GOROOT 那一行说明 Go 也去自己的 src 底下找过,因为标准库就在那,第三方包理论上也能塞进去,虽然没人这么干。第二行 from $GOPATH 就是老规矩的位置,看到这行输出,你就知道自己该把包放到哪,或者该把哪个变量改对,这比任何一篇讲环境变量的文章都直观,因为它是按你这台机器的真实路径打印出来的。

而模块模式下的报错完全不长这样,它说的是 no required module provides package ...,后面跟一句 to add it: go get ...,直接告诉你下一步敲什么。两种报错对应两套机制,看到哪句就知道自己在哪套里,这个判断比记住任何一句命令都有用。我在带人的时候发现,把这四种报错各自对应的机制讲一遍,比讲十个环境变量管用,因为报错是他们会天天撞上的东西,而环境变量一辈子可能只看两次。

走向外的门被墙挡住了

GOPROXY 是第四个和前面三个一样重要、但名字不像的变量,它管的是去哪里下载依赖。默认值是 https://proxy.golang.org,direct,逗号分隔表示先问第一个,失败了再走第二个,direct 的意思是直接连源站,也就是去 GitHub 上 clone,这套默认在中国大陆基本等于不能用,我实测过一次,等满了 21 秒才失败。

1
GOPROXY=https://proxy.golang.org go list -m -versions github.com/google/uuid
1
2
3
4
go: module github.com/google/uuid: Get "https://proxy.golang.org/github.com/google/uuid/@v/list":
dial tcp 142.251.33.209:443: connectex: A connection attempt failed because
the connected party did not properly respond after a period of time, or
established connection failed because connected host has failed to respond.

不是拒绝,是超时。

超时比拒绝更烦人,因为拒绝是立刻的,你能马上换方案,超时得等,而 direct 那一档也救不了,direct 是去连 github.com,一样的结果。换成国内镜像就通了,https://goproxy.cn 是七牛维护的,实测一次就回。

1
GOPROXY=https://goproxy.cn,direct go list -m -versions github.com/pkg/errors
1
2
github.com/pkg/errors v0.1.0 v0.2.0 v0.3.0 v0.4.0 v0.5.0 v0.5.1 v0.6.0
v0.7.0 v0.7.1 v0.8.0 v0.8.1 v0.9.0 v0.9.1

这个设置值得用 go env -w 写死,因为它不是一次性的,每换一台机器、每重装一次 Go 都要重来一遍。GOSUMDB 跟着一起写,是因为校验和数据库 sum.golang.org 也在墙外,GOPROXY 通了它照样会卡住,这时 go mod tidy 会报一个看起来毫不相干的错,verifying module: ...,实际卡在网络上。

要说明的是 GOSUMDB=off 不等于放弃校验。

go.sum 那个文件还在,本地比对照做,只是不再去网上问第三方的数据库,这两件事经常被混为一谈,其实一个是本地账本,一个是远端账本,关掉远端不影响本地那本。

环境坏了的时候,症状长得像别的问题

这套变量配错之后,报错往往不在环境这个方向上,这是最容易浪费时间的地方。

我这台机器上出过一个很典型的例子,go test 报 testing/internal/testdeps: cannot find package testmain,看着像是标准库缺了一块,或者 Go 装坏了,实际原因是 GOCACHE 指到了一个写不进去的目录,测试的辅助包编不出来。同一个根因还能长出别的形状,-gcflags='-m' 报 open D:\Go\cache\76\...-d: Access is denied.,go mod tidy 报 verifying module: ... Access is denied.。

三个报错,三种说法,一个原因。

所以看到 Go 报出莫名其妙的标准库相关错误时,第一件事不是重装,是先把这几个变量导成临时目录试一遍。

1
2
3
4
export GOCACHE="$TEMP/gocache"
export GOMODCACHE="$TEMP/gomod"
export GOPATH="$TEMP/gopath"
export GOSUMDB=off

这套导完之后同样的代码就能跑,那就说明确实是环境问题,不是代码问题,也不是安装问题。本专栏后面每一篇的实测数字都是在这套环境下跑出来的,环境那一节记了完整的导出命令,你照着抄一遍,后面所有输出都能对上,包括那些看着像玄学的耗时数字,其实一半以上都是缓存状态决定的。

一句话记住

GOROOT 是 Go 的,GOPATH 是你的,GOBIN 是可执行文件的,GOPROXY 是下载的路,GOMODCACHE 和 GOCACHE 是两处临时堆场。

五个地址全都不一样,报错的时候先问自己一句,这个错是哪一层在说话。