安装 Go 并运行第一个程序

安装受支持的 Go 工具链、验证 go env、创建 module、运行并测试第一个可执行程序，建立可重复的本地开发基线。

#type / howto #status / growing #tech / dev #resource / go

[!info] 关联笔记

安装 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. go test ./... 至少能对含测试的包通过（或空包无失败）
  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；当前目录无测试时 go test ./... 以成功退出（no tests to run 仍可接受，退出码 0）。

核心步骤与准确模型

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 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 通路

// greet.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. 多版本并存

本机同时有旧安装与新安装时，where go/which go 可能指向意外版本。以 go version 为准。

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 是否与你的机器一致。

实验 2：Hello

go run . 输出 hello, Go。

实验 3：构建产物

go build -o hello . 后直接执行二进制，不依赖 go run。

实验 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 + 自测）
创建于 2026/7/11 更新于 2026/7/15