[!info] related notes

• 所属 MOC：工具链与工程结构 · 学习路线
• 后续概念：程序结构、Modules、构建与部署
• 哲学入口：起源与设计哲学
• Windows 方案：使用 Scoop 安装并配置 Go 环境

安装 Go 并运行第一个程序

这个概念为什么出现

学语法之前，必须先有一条可验证的工具链路径：

• go 命令在 PATH 中
• 版本与平台信息可知
• 能创建 module（而不是 GOPATH 时代的旧习惯）
• 能 go run / go test / go build

否则后续所有“报错”都分不清是代码问题还是环境问题。本篇是 howto：目标不是讲完语言，而是装好、跑通、知道坏了怎么查。

[!abstract] 一句话理解 从官网或可信包管理器安装工具链 → 用 go version/go env 验收 → go mod init 建模块 → 写 package main → go run/go test 证明环境可用。

目标

完成后应满足：

1. go version 输出受支持的稳定版工具链
2. go env GOROOT GOPATH GOOS GOARCH 可解释
3. 当前目录有 go.mod，go run . 打印预期输出
4. 加入 TestGreet 后，go test ./... 实际发现并运行该测试；无测试包退出 0 只验证构建通路。
5. 能区分“环境坏了”与“代码错了”

最小可运行示例

package main

import "fmt"

func main() {
	fmt.Println("hello, Go")
}

mkdir hello-go && cd hello-go
go mod init example.com/hello
# 将上面代码保存为 main.go
go fmt ./...
go run .
go test ./...

预期：go run . 打印 hello, Go；已有 main.go 但尚无测试文件时，go test ./... 通常显示 [no test files] 并退出 0。这不等于业务经过测试，继续加入下方 TestGreet。

核心步骤与准确模型

1. 安装受支持版本

• 首选：Go 下载页 的官方安装包
• Windows 也可用可信包管理器，见 Scoop 方案
• 不要使用来源不明的“精简包/破解包”

[!warning] 版本边界 Go 发布策略下，每个主版本的支持窗口有限。安全修订优先升级；学习笔记不把补丁号写成永久真理。查看当前策略：Release History。

2. 验证工具链

go version
go env GOROOT GOPATH GOOS GOARCH GOTOOLCHAIN

变量	含义
GOROOT	工具链安装位置
GOPATH	模块缓存与 go install 默认相关路径的根；现代项目不必放在 $GOPATH/src
GOOS/GOARCH	目标操作系统与架构
GOTOOLCHAIN	工具链自动选择策略（Go 1.21+ 相关）

3. 模块是项目边界

仅在新项目尚无 go.mod 时执行；若已完成上面的最小示例，无需重复 init。

go mod init example.com/hello

生成 go.mod：声明模块路径与语言版本基线。
模块是版本与依赖单位；包是编译单位。详见 Modules。

4. 第一个程序的结构

package main

import "fmt"

func main() {
	fmt.Println("hello, Go")
}

• 可执行程序必须是 package main 且有 func main()
• 导入路径标准库用短名 "fmt"
• 更多结构见 程序结构

5. 格式化、运行、测试、构建

go fmt ./...
go run .          # 编译到临时文件并执行
go test ./...     # 跑当前 module 测试
go build -o hello .  # 产出二进制

6. 加一个测试证明 test 通路

用下方内容替换原 main.go，再新增 greet_test.go；不要同时保留两个 main 函数。

// main.go（替换原内容）
package main

import "fmt"

func greet(name string) string {
	return fmt.Sprintf("hello, %s", name)
}

func main() {
	fmt.Println(greet("Go"))
}

// greet_test.go
package main

import "testing"

func TestGreet(t *testing.T) {
	if got := greet("Go"); got != "hello, Go" {
		t.Fatalf("got %q", got)
	}
}

go test ./...

设计动机

1. 官方工具链一体
   格式化、构建、测试、依赖同一 go 命令入口。
2. 模块可复现
   从第一天就用 go.mod，避免 GOPATH 旧路径心智。
3. 失败可定位
   先固定环境基线，再学语言细节。

边界情况与反直觉行为

1. 装了但终端找不到 go

常见于未刷新 PATH、装到用户目录但当前 shell 未继承。重开终端；Windows 检查“环境变量”。

2. 在错误目录 go run

go: cannot find main module → 先 go mod init 或进入含 go.mod 的目录。

3. 代理与 sum 校验

企业网/地区网络可能导致下载慢或失败。应配置可信模块代理，而不是随意 GOSUMDB=off 关掉校验。见官方 Module proxy 与 Managing dependencies。

4. 多版本并存

本机多版本并存时，用 Windows 的 where.exe go、PowerShell 的 Get-Command go 或 POSIX shell 的 command -v go 检查入口。go version 还可能反映自动选择后的工具链，结合 GOTOOLCHAIN、go.mod 与 go.work 检查。

5. go test 在无测试包

无 *_test.go 时通常仍退出 0，并提示无测试；这不代表业务已测。

常见误区

[!warning] 常见误区：继续把项目塞进 GOPATH/src 错误：以为 2017 年前的布局仍是唯一正确方式。
正确：任意目录 + go mod init。

[!warning] 常见误区：用 go get 当“运行主程序” 错误：把依赖命令与运行命令混用。
正确：跑本地 main 用 go run/go build。

[!warning] 常见误区：跳过 go fmt 错误：提交私有缩进风格。
正确：gofmt/go fmt 是协作默认；编辑器保存时格式化。

[!warning] 常见误区：版本过旧仍跟新教程 错误：教程用 1.22 语法，本机 1.18。
正确：对齐版本或看清语言特性所需最低版本。

与相邻概念对比

概念	差异
Modules	依赖与版本算法；本篇只完成 init
构建部署	发布级标志与交叉编译
程序结构	包、导入、文件组织细节
IDE 插件	便利层；不能替代命令行验收

工程实践

1. 安装后立刻跑 version + env + 最小 module，写入团队 onboarding。
2. 固定 CI 与本地主版本相近，减少“我这边能过”。
3. 编辑器：官方 gopls 语言服务；保存时 format + 可选 imports 整理。
4. 私有模块：配置 GOPRIVATE，勿关全局校验。
5. Windows：路径、执行策略、杀毒误报偶尔干扰；优先官方安装包或文档化的 Scoop 流程。
6. 第一个 PR 级检查清单：fmt、test、vet（后续再加 lint）。

可验证实验

实验 1：版本与平台

核对 go version 和 go env GOOS GOARCH；后两者是构建目标，交叉编译配置下可与主机不同，主机信息可看 GOHOSTOS/GOHOSTARCH。

实验 2：Hello

go run . 输出 hello, Go。

实验 3：构建产物

POSIX shell 中用 go build -o hello . 后执行 ./hello；Windows 中用 go build -o hello.exe . 后执行 .\hello.exe。

实验 4：测试通路

加入 TestGreet，go test ./... 通过；故意改期望值看失败输出。

实验 5：错误模块路径

在无 go.mod 的临时目录 go run .，阅读报错并修复。

本节总结

• 目标：工具链可用、module 已建、run/test/build 通路打通。
• 关键命令：go version、go env、go mod init、go run、go test、go build。
• 心智：现代 Go 以 module 为中心，而不是 GOPATH 项目堆。
• 下一步：程序结构 与 Modules；需要发版时读 构建与部署。

自测题

概念题

1. GOROOT 与 GOPATH 今天各主要干什么？
2. 为什么第一天就要 go mod init？
3. go run 与 go build 的差别？

操作推理题

同事发来只有 main.go、没有 go.mod 的目录，你在该目录执行 go run . 可能看到什么？如何最小修复？

工程思考题

团队一半人 Go 1.21、一半人 1.23，可能出现哪些协作摩擦？如何约定？

参考答案

展开

1. GOROOT 是工具链安装位置；GOPATH 仍用于缓存与默认安装路径等，但源码不必放在其 src 下。
2. 明确模块路径与语言版本，进入官方依赖与构建模型，避免旧 GOPATH 习惯。
3. run 编译并执行（临时产物）；build 留下可分发二进制。
   操作：常报找不到 main module；在目录 go mod init <path> 后重试。
   工程：语言特性与标准库差异、CI 不一致；约定最低版本与 toolchain，CI 钉死版本。

延伸阅读与资料来源

资料	类型	支撑
Install Go	官方文档	安装
Tutorial: Get started with Go	官方教程	Hello 与 module
Managing dependencies	官方文档	依赖与代理
Command go	命令参考	env/run/test/build
Release History	官方文档	版本支持

---

笔记元信息

• 建议文件名：install-go-and-run-first-program.md
• 所属阶段：入门工具链
• 学习顺序：第一课 howto
• 建议下一篇：Go 程序结构 或 Go 起源与设计哲学
• 本篇状态：已深化（完整 howto + 自测）