go 这一条命令帮你干了多少事

难度 ★★☆☆☆ · 前置:go.mod 记你要什么,go.sum 记你拿到了什么 | 一句话结论:go build 之所以第二次快九倍,是因为它根本没在编译,它先算一遍要做什么,发现输入一个字节都没变就直接跳过;go vet 查的是能编过但大概率是错的,gofmt 查的是格式,两者互不替代。

刚开始用 Go 的时候,我在一个目录里反复敲 go run main.go,每次都等两三秒,觉得很正常,编译型语言嘛,总要给你点脸色看看。直到有一天我在同事机器上看到他改完一行代码按了下回车,终端几乎立刻就出来了结果,我问他是不是装了什么加速插件,他说没有,就是打了一个点。这个事情我想了很久才明白,不是他的机器快,是我一直用错了写法。go run main.go 交给编译器的是一串文件名,go run . 交给它的是一个包,包级别的构建缓存只有在后一种情况下才生效。当时我刚入行一个多月,这类差别在我眼里属于玄学,只能靠死记,后来越挖越深才发现,go 这套工具链里每一处让人觉得莫名其妙的地方,背后都有一条能说清楚的规则。

后来我把整个流程拆开看了一遍,go 这个命令底下其实挂着十几个独立的小工具,它自己只做一件事,看第一个参数是什么,然后把剩下的全转给对应的工具。编译有 compile,链接有 link,格式化有 gofmt,文档有 doc,包信息有 list,这些全躺在 GOROOT/pkg/tool 底下,你甚至可以跳过 go 直接调它们。理解了这一层,后面那些看起来莫名其妙的行为就都有了解释,比如为什么缓存的粒度是包不是文件,为什么 vet 是测试的一部分而不是编译的一部分。我后来给新人讲 Go 总是先讲这一层,因为不讲这个,go 就只是一堆要背的命令,讲了之后它变成一个有结构的东西,忘了某个子命令也知道该去 go help 里翻哪一段。

这两件事我最初完全没分清。

build 第二次为什么快九倍

先把这个数字量出来。同一个项目,清掉缓存之后第一次编译,再编一次,改一行再编一次。

1
2
go clean -cache
time go build ./...
1
real    0m3.747s

紧接着不改任何东西,再编一次,得到的是 0m0.421s。差了将近九倍。

然后随便改一行代码里的字符串,第三次,0m0.909s。这个数字最能说明问题,改了一行,只重编一个包,所以比全清之后快,又比完全不动要慢。

原因是 Go 的构建缓存按内容寻址,它把每个包的源码、依赖的导出数据、编译参数一起算成一个哈希,拿这个哈希去缓存目录里找,找到就直接用产物,一个字节的机器码都不用重新生成。这个哈希里连编译器的版本都算进去了,所以升级 Go 之后缓存整体失效一次,这不是 bug,是设计。还有一层更细的,缓存的键不只看输入,还看动作本身,编译和链接是两个动作,同一份输入算出来的键也不一样,所以你不可能拿一个链接产物去当编译产物用。这解释了两件事,一是第一次为什么慢,二是改一行为什么只要零点九秒,因为改动只影响一个包,上游全部命中,下游那几个包虽然要被重新链接,但它们的机器码还是直接从缓存里取。

判断缓存有没有起作用,最直接的办法是看那个目录的大小变化,go env GOCACHE 拿到路径,第一次编完会长一大截,第二次几乎不动。也可以加一个 -x 看它到底执行了哪些子命令,缓存命中的时候,compile 那一行根本不会出现。

数字说的是缓存,不是编译器。

有一点值得单独说,go run 也用这套缓存。所以 go run main.go 慢不是因为 run 慢,是因为那种写法每次给编译器的是一个文件列表而不是一个包,包级别的缓存用不上,只能整个走一遍,连导入解析都要重做。同一个目录,把参数从 main.go 换成 .,速度立刻不一样,这个差别我第一次知道的时候有点惊讶,因为两个命令看起来只差一个点,一个是文件名一个是目录名,结果动的是整套缓存策略。类似的还有在子目录里跑 go run *.go,看起来是个聪明的写法,实际上把缓存彻底废掉了,项目一大就越跑越慢。

run、build、install 三者的分工

三个命令听起来都在生成一个能跑的东西,实际上边界很清楚。

go build 只负责编译,产物落在当前目录,名字默认取目录名。它不安装,不改任何全局状态,你可以把它当成一个纯函数,输入源码输出二进制,中间除了缓存不留痕。

go run 是编译加立刻执行,产物在临时目录里,跑完就没了。它适合验证一小段逻辑,不适合跑服务,因为进程一退出你就拿不到那个二进制了,也没法用 -ldflags 之类的手段把版本号打进去。

go install 才是真正会动全局的那个,它编译完把产物放到 $GOBIN 或者 $GOPATH/bin,那个目录又在 PATH 里,所以你就能直接敲命令名了。模块模式下装第三方工具的标准写法是带版本号的,go install github.com/xxx/yyy@latest,这个写法不带版本号会报错,因为模块模式不知道该给你装哪个版本。

这里有个我踩过的坑值得提一句,go install 之前如果 go env 里的 GOBIN 被改过,产物会跑到那个目录去,而不是你以为的 $GOPATH/bin。我在装 Go 那篇里详细写过这个,一句话就是,装完找不到命令,先跑 go env GOBIN,别急着怀疑 PATH。

vet 查的不是格式,是可疑

go vet 这个名字起得不好,容易被想成代码检查器的统称,实际上它只查一类问题,能编译通过、运行也可能不报错,但语义上几乎肯定不是你想写的东西。

最典型的是格式化字符串和参数对不上。

1
func bad() { fmt.Printf("%d\n", "str") }
1
go vet ./...
1
bad.go:5:26: fmt.Printf format %d has arg "str" of wrong type string

这个错误编译器不会报,因为 Printf 的签名是 func(string, ...any),传个字符串进去类型完全合法,只有 vet 会去看那个 %d 和参数的实际类型。所以它抓的是类型系统管不到的语义层。

vet 默认还能查出的东西有这些类别,锁的复制(sync.Mutex 被赋值传走)、struct 标签写错、range 循环变量被闭包捕获、Printf 家族参数不匹配、无用的 append 结果、可疑的位运算。这个清单不算长,但它覆盖的正是经验不足的人最容易犯的那几类错,每一条我在别的项目里都见过实际案例,尤其是 range 变量那个,Go 1.22 改了循环变量的作用域之后才从语言层面解决,在那之前只能靠人盯。锁的复制那条也值得多说一句,一个 sync.Mutex 被当成值传进函数,锁住的是副本,保护不到原来的数据,这种 bug 编译期完全看不出来,跑起来才发现怎么加锁都不管用。

所以测试过了,基本等于 vet 过了。

go test 默认会跑一遍 vet,这是很多人不知道的。反过来说,如果你的测试因为 vet 报错而失败,看到的输出会是 vet: xxx.go:5:26: ... 这种前缀,别去代码里找断言的问题。

gofmt 只管一件事

格式。它不查语义,不查可疑写法,只把代码按固定规则重排,制表符、空格、括号位置、对齐。

gofmt -l 列出需要改的文件,gofmt -d 打出具体会改什么。

1
gofmt -l .
1
ugly.go
1
gofmt -d ugly.go
1
2
3
4
5
6
7
8
diff ugly.go.orig ugly.go
--- ugly.go.orig
+++ ugly.go
@@ -1,2 +1,3 @@
package main
-func bad2() {}
+
+func bad2() {}

注意这个 diff 里改了两处,一个函数前的空行,一个多余的空格。这种改动没有对错之分,它只是把所有人都这么写这件事固化成了工具,好处是代码评审里再也不用为空格争论,坏处是你喜欢的某种排版方式会恒定地被工具改回去。我一开始很抗拒,觉得它把我精心对齐的东西打乱了,后来发现 gofmt 对结构体字段的对齐其实是保留的,它打乱的只是我那些自以为有意义的空行,而一旦放弃抵抗,团队的 diff 就变干净了,评审的时候没人再提空格,讨论能落到真正的逻辑上。

go fmt ./... 是 gofmt -l -w 的包装,它会对整个包写回文件,而 gofmt 自己要加 -w 才写。它们的区别在递归行为上,gofmt 按目录递归,go fmt 按包递归,对大多数项目结果一样,但如果你有非 Go 文件或者被构建约束排除的目录,走 go fmt 更准。

-gcflags 能看见编译器的犹豫

这个是整个工具链里最值得花时间的一个参数,因为它是唯一能让你看见编译器怎么想的窗口。

1
go build -gcflags='-m' ./...
1
2
3
4
5
6
./main.go:5:6: can inline add
./main.go:12:17: inlining call to add
./main.go:12:13: inlining call to fmt.Println
./main.go:8:11: make([]int, 0, 4) escapes to heap
./main.go:10:13: append escapes to heap
./main.go:12:25: s escapes to heap

两类信息混在一起,can inline 是内联决策,escapes to heap 是逃逸分析。内联的意思是那个函数的函数体被直接摊开在调用处,省掉一次函数调用,逃逸的意思是那个变量没能在栈上活完整个函数,得挪到堆上去,代价是一次分配加一份 GC 负担。前者影响速度,后者影响内存,两件事经常被混为一谈,很多人为了消掉一行 escapes 去改代码,改完速度反而慢了,因为他动的是热路径上的内联边界。这两件事还有一层联动,一个函数被内联之后,它内部的变量有机会留在调用者的栈帧上,所以那两行 inlining call to 不只是噪音,它跟下面的 escapes 是连着的。

加上第二个 -m,输出会多出理由。

1
go build -gcflags='-m -m' ./...
1
2
3
4
./main.go:5:6: can inline add with cost 4 as: func(int, int) int { return a + b }
./main.go:7:6: cannot inline main: function too complex: cost 111 exceeds budget 80
./main.go:12:17: ~r0 escapes to heap in main:
./main.go:12:17: flow: {storage for ... argument} ← &{storage for ~r0}:

cost 111 exceeds budget 80 这句是内联失败的完整理由,编译器的预算是一个函数八十个代价单位,超了就不内联。这条信息在优化热点路径的时候特别有用,因为它告诉你不是你写错了,是编译器觉得不划算,你只能靠改函数结构去把这个数降下来,比如把一个长函数拆成两段,或者把里面那个 defer 挪到别处,实测经常能直接省下一次函数调用。这个八十不是配置项,是编译器里写死的常量,改不了,能改的只有你的函数。

逃逸那几行 flow: 更细,它把整个引用链打出来了,谁指向谁,一路指到堆。读这种输出第一次会晕,习惯之后是排查内存分配的第一手材料。

顺带说一句,-gcflags 只对本次编译生效,写进 go env -w 是没用的,它不是一个环境变量,是一个传给编译器的标志。

交叉编译卡住的地方不是 GOOS

改两个环境变量就能编出别的平台的产物,这件事 Go 做得比几乎所有语言都干净。

1
2
GOOS=linux GOARCH=arm64 go build -o h_arm .
file h_arm
1
h_arm: ELF executable

不装虚拟机,不装交叉编译器,就两个环境变量。原因是 Go 的标准库自带了一份纯 Go 的运行时和系统调用封装,它不需要借助宿主机的 libc。

但这条路有个明确的边界,一旦项目里用了 cgo,交叉编译立刻崩。

1
GOOS=linux GOARCH=arm64 CGO_ENABLED=1 go build -o hx .
1
2
3
4
5
# runtime/cgo
gcc_mmap.c:10:10: fatal error: sys/mman.h: No such file or directory
10 | #include <sys/mman.h>
| ^~~~~~~~~~~~
compilation terminated.

这个报错很能说明问题,它不是在说你的代码有问题,它是在说本机的 gcc 找不到目标平台的系统头文件。cgo 的本质是调用宿主编译器去编一段 C,而宿主编译器只会为宿主平台编,交叉这一步就断了。所以问题从来不在 GOOS 和 GOARCH 这两个变量上,它们只是把请求提出去了,真正执行的那一环没有配套的工具链。我见过不少人在这条路上耗掉一下午,换 GOOS、换 GOARCH、换 Go 版本,其实换哪个都没用。

所以 Go 交叉编译很方便这句话的完整版本是,不用 cgo 的时候很方便。判断你的项目有没有用到 cgo,跑一句 go list -deps . | grep runtime/cgo 就够了,有输出就是用了。常见的来源是 net(DNS 解析可以走 cgo)、os/user、database/sql 的部分驱动,还有任何显式 import "C" 的代码,很多人在没意识到的情况下就已经把 cgo 引进来了,等到要交叉编译才发现。

CGO_ENABLED=0 能把这些绕过去,代价是 DNS 解析改走纯 Go 实现,某些容器环境里行为会有细微差别,这一条在排查跨环境问题时经常是决定性的一环。

三件收尾的小事

go doc 是本地文档,不用联网,这一点在断网的机器上就是救命稻草。

1
go doc fmt.Println
1
2
3
4
5
6
package fmt // import "fmt"

func Println(a ...any) (n int, err error)
Println formats using the default formats for its operands and writes to
standard output. Spaces are always added between operands and a newline
is appended. It returns the number of bytes written and any write error

这个比去网站上查快得多,尤其是查标准库的时候。go doc -all 包名 打整个包的文档,go doc 类型.方法 直接定位到某个方法。

go list 是包信息的查询接口,-f 参数可以按模板输出字段,-deps 把整棵依赖树打平。我常用的就是下面这一句,排查一个包到底编了哪些文件的时候,它比翻目录可靠,因为它自动排除了构建约束不匹配的文件。

1
go list -f '{{.ImportPath}} {{.Name}} {{join .GoFiles ","}}' ./...
1
example.com/gcmd main main.go

体积这事,一行参数就能解决一半。

1
2
go build -o h.exe . && ls -l h.exe
go build -ldflags='-s -w' -o hs.exe . && ls -l hs.exe
1
2
2491904 h.exe
1655296 hs.exe

少了三分之一的字节。代价是 panic 的堆栈里没有文件名和行号,线上出了崩溃很难定位,只能靠日志里的上下文去猜位置,猜错了就是半小时起步。我的做法是发布版本不 strip,只在内网或者镜像体积敏感的地方用,因为省下来的那一兆多,换一次排障时间就亏回去了,而且这个损失不可逆,出事之后你没法把符号表补回来。

这几个数字都是同一份源码在同一台机器上量的,换个项目比例会不一样,但量级差不多。