01 起步与工具链

01 起步与工具链

本页回答三个问题：这段代码怎么跑起来、依赖怎么管、怎么交付到别的机器上。

基线：Go 1.27.1 / darwin/arm64。命令输出为本机实跑结果。

一张图看懂 go 命令

go 不是编译器，是构建系统。你只跟它打交道，真正干活的 compile/link 由它调度——go build -x 能看到全过程。

flowchart TB
    GO(["go 命令"])

    GO --> BUILD["构建类"]
    GO --> MOD["依赖类"]
    GO --> QUAL["质量类"]
    GO --> ENV["环境类"]

    BUILD --> B1["go run<br/>编译并立即执行"]
    BUILD --> B2["go build<br/>产出可执行文件"]
    BUILD --> B3["go install<br/>装到 GOBIN"]
    BUILD --> B4["go test<br/>编译并跑测试"]

    MOD --> M1["go mod<br/>init/tidy/download/why"]
    MOD --> M2["go get<br/>增删升降依赖"]
    MOD --> M3["go work<br/>多模块工作区"]
    MOD --> M4["go vendor<br/>依赖拷进仓库"]

    QUAL --> Q1["go fmt<br/>格式化，不可谈判"]
    QUAL --> Q2["go vet<br/>静态检查常见错误"]
    QUAL --> Q3["go doc<br/>命令行看文档"]

    ENV --> E1["go env<br/>查看/写入环境变量"]
    ENV --> E2["go version -m<br/>查看二进制里嵌的模块信息"]
    ENV --> E3["go tool<br/>pprof/cover/trace 等子工具"]

命令全表

构建与运行

依赖与模块

质量与文档

go vet 到底能查什么——这些是它最值钱的几条，写代码时是硬错误级别：

💡 完整清单用 go tool vet help 查看（1.27.1 共注册 36 个 analyzer）。⚠️ go vet 抓不到 nil 接口陷阱——它没有这个检查项，那类问题只能靠 08 里讲的规则与代码审查（或 staticcheck）。

环境变量

flowchart LR
    subgraph BUILD["影响构建"]
        B1["GOOS / GOARCH<br/>目标平台"]
        B2["CGO_ENABLED<br/>0=纯静态"]
        B3["GOFLAGS<br/>默认命令行参数"]
        B4["GOTOOLCHAIN<br/>工具链切换"]
    end

    subgraph CACHE["影响缓存"]
        C1["GOCACHE<br/>编译缓存"]
        C2["GOMODCACHE<br/>依赖缓存"]
        C3["GOPATH<br/>旧时代根目录"]
    end

    subgraph NET["影响网络"]
        N1["GOPROXY<br/>模块代理"]
        N2["GOSUMDB=off<br/>或 GOPRIVATE / GONOSUMDB<br/>跳过校验 ⚠️"]
        N3["GOFLAGS=-mod=vendor<br/>强制走 vendor"]
    end

    subgraph RUNTIME["影响运行"]
        R1["GOMAXPROCS<br/>P 的数量"]
        R2["GOGC / GOMEMLIMIT<br/>GC 行为"]
        R3["GODEBUG<br/>运行时开关"]
    end

查看与写入（区分大小写，写入后持久化到 go env 配置文件）：

1
2
3
4
5
6
7

$ go env GOPROXY GOMODCACHE
https://goproxy.cn,direct
/Users/lx/go/pkg/mod

$ go env -w GOPROXY=https://goproxy.cn,direct   # 持久写入
$ go env -u GOPROXY                             # 撤销，回到默认
$ go env -w GOFLAGS=-trimpath

⚠️ go env -w 写的是用户级配置，优先级高于系统默认但低于进程环境变量。CI 里建议直接用环境变量注入，不要改机器状态。

从零到交付

flowchart LR
    A["mkdir demo<br/>cd demo"] --> B["go mod init<br/>example.com/demo"]
    B --> C["写 main.go<br/>package main + func main"]
    C --> D["go mod tidy<br/>补齐依赖"]
    D --> E["gofmt + go vet<br/>格式化与静态检查"]
    E --> F["go test ./...<br/>跑测试"]
    F --> G["go build<br/>-ldflags 注入版本"]
    G --> H["交叉编译<br/>GOOS/GOARCH"]
    H --> I["交付单个二进制"]

最小可用骨架（cmd/ 布局适合多命令项目，单命令项目直接扁平放也行）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

demo/
├── go.mod
├── go.sum
├── main.go              # package main，仅做装配
├── internal/            # 只能被本模块导入 🔥
│   └── user/
│       ├── user.go
│       └── user_test.go
└── cmd/
    └── api/
        └── main.go      # 多个可执行入口时使用

run / build / install 到底差在哪

三者都编译同一条链路，差别只在产物去哪。

• go run
• go build
• go install
• 三者对照

1
2

$ go run .
Hello, 世界

1
2
3

$ go build -o demo .
$ ls
demo  go.mod  main.go

1
2
3
4

$ go install ./cmd/api
$ ls $(go env GOPATH)/bin
api
$ api --help

1

$ go install golang.org/x/tools/cmd/stringer@latest

依赖管理

go.mod 的每一行长什么样

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

module example.com/demo        // 模块路径，也是别人 import 你的前缀

go 1.27.1                     // 语言版本 + 最低工具链要求 🆕 1.21 起可带补丁号

toolchain go1.27.1            // 可选：显式锁工具链

require (
	github.com/google/uuid v1.6.0   // 直接依赖
	golang.org/x/text v0.14.0       // indirect 标记的是间接依赖
)

require golang.org/x/sys v0.15.0 // indirect

exclude github.com/bad/pkg v1.0.0   // 排除某个版本

replace github.com/a/b => ../b      // 本地替身，调试自己的库时必用 🔥

retract v1.0.5                      // 作者声明「别用这个版本」

依赖操作决策图

flowchart TB
    Q(["我要动依赖"]) --> Q1{"加新的？"}
    Q1 -- 是 --> A1["import 后 go mod tidy"]
    Q1 -- 否 --> Q2{"升级？"}
    Q2 -- 单个包 --> A2["go get pkg@v1.3.0"]
    Q2 -- 全部 --> A3["go get -u ./... ⚠️ 先看 diff"]
    Q2 -- 否 --> Q3{"删旧的？"}
    Q3 -- 是 --> A4["删 import 后 go mod tidy"]
    Q3 -- 否 --> Q4{"想知道它为啥在？"}
    Q4 -- 是 --> A5["go mod why -m pkg"]
    Q4 -- 否 --> A6{"要离线/审计？"}
    A6 -- 是 --> A7["go mod vendor"]

可复现构建三件套

1
2
3

$ go mod tidy          # 1. 依赖清单与代码一致
$ go mod verify        # 2. 校验下载内容未被篡改
$ go build -trimpath   # 3. 产物不含本机路径，处处一致

⚠️ go.sum 必须提交。它记录每个模块的哈希，是供应链安全的底线；删了会导致校验失败，改了会导致构建结果不可信。

交叉编译

Go 交叉编译不需要工具链，只要目标平台是纯 Go 支持的组合。

1
2
3
4
5
6
7

$ GOOS=linux   GOARCH=amd64 CGO_ENABLED=0 go build -o api-linux-amd64 .
$ GOOS=linux   GOARCH=arm64 CGO_ENABLED=0 go build -o api-linux-arm64 .
$ GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -o api.exe .
$ GOOS=darwin  GOARCH=arm64 CGO_ENABLED=0 go build -o api-mac-arm64 .

$ file api-linux-arm64
api-linux-arm64: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), statically linked, ...

CGO_ENABLED=0 的意义：一旦启用 cgo，产物就依赖目标平台的 C 库，交叉编译需要对应交叉工具链，且不再是静态二进制。所以「单文件部署」的前提是不引入 cgo。

1
2

$ go tool dist list | wc -l        # 支持的平台组合总数
$ go tool dist list | grep linux   # 只看 linux

构建标记与版本注入

编译期注入版本信息

这是生产二进制最该有的一段代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

package main

import (
	"fmt"
	"runtime"
)

// 这三个变量由 -ldflags 在链接期覆盖，默认值只在 go run 时出现
var (
	version = "dev"
	commit  = "none"
	date    = "unknown"
)

func main() {
	fmt.Printf("version=%s commit=%s date=%s go=%s\n",
		version, commit, date, runtime.Version())
}

1
2
3

$ go build -ldflags "-X main.version=v1.2.3 -X main.commit=abc1234 -X main.date=2026-09-21T00:00:00Z" -o app .
$ ./app
version=v1.2.3 commit=abc1234 date=2026-09-21T00:00:00Z go=go1.27.1

⚠️ -X 的格式是 -X importpath.name=value；对 main 包写 main.version 即可。变量必须是字符串类型，且不能被编译器优化掉（保证它被引用到）。

构建标记（build tags）

放在文件顶部、package 之前，后面必须空一行：

1
2
3
4
5

//go:build linux && amd64

package platform

func PageSize() int { return 4096 }

1
2

$ go build -tags=integration ./...
$ go test -tags=integration ./...     # 跑需要外部依赖的集成测试

⚠️ 旧的 // +build 语法已废弃 🪦，1.17 起统一用 //go:build。两种混写会被 gofmt 纠正。

看二进制里到底有什么

排查线上问题时，「这个二进制是哪次提交构建的」往往比日志更重要。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

$ go version -m ./app
./app: go1.27.1
	path	example.com/demo
	mod	example.com/demo	(devel)
	build	-buildmode=exe
	build	-compiler=gc
	build	CGO_ENABLED=0
	build	-ldflags="-X main.version=v1.2.3"
	build	-trimpath=true
	build	vcs.revision=9f3a1c2...
	build	vcs.time=2026-09-21T02:00:00Z
	build	vcs.modified=false

💭 只加 -buildvcs=false 就能关掉 VCS 信息嵌入；如果你的构建环境没有 git，默认不会报错（除非显式要求）。

本页陷阱速查

📘 官方参考：Command go、Go Modules Reference、Go 1.27 Release Notes

➡️ 下一节：02 词法与语法骨架