English

Go 环境搭建与第一个程序

AI 辅助生成本文由 AI 起草并经人工核查，示例均标明软件版本；发现错误请以官方文档为准。

Go 1.24

Go 的入门门槛不高，但「安装完之后代码放在哪、go run 到底做了什么」经常让人困惑。这一篇把环境与最小工作流一次理清。

安装与验证

从 go.dev/dl 下载对应平台安装包。Windows 用 MSI 安装后需要重开终端让 PATH 生效。

go version
# go version go1.24.0 windows/amd64

看一眼关键环境变量：

go env GOPATH GOMODCACHE GOPROXY
  • GOPATH：工作区根目录，默认 ~/go（Windows 为 %USERPROFILE%\go）。
  • GOMODCACHE：下载的第三方包缓存，默认在 GOPATH/pkg/mod。
  • GOPROXY：模块代理，国内网络慢时可以设为 https://goproxy.cn,direct。
go env -w GOPROXY=https://goproxy.cn,direct

第一个程序

新建目录并初始化模块：

mkdir hello && cd hello
go mod init example/hello

会生成 go.mod：

module example/hello

go 1.24

写 main.go：

package main

import "fmt"

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

运行：

go run .
# Hello, Go

go run 会在临时目录编译并执行，不留下可执行文件；要产出二进制用 go build：

go build -o hello .
./hello          # Windows 下是 hello.exe

三个必须知道的命令

go fmt ./...     # 格式化（等价于 gofmt -w）
go vet ./...     # 静态检查：可疑的格式化字符串、无用的赋值等
go test ./...    # 运行测试

Go 的格式没有争议：go fmt 决定缩进、空格、换行，团队不需要讨论风格，编辑器保存时自动执行即可。

go vet 能抓到编译器不报但明显有问题的代码，建议每次提交前跑一遍。

模块模式：不再有 GOPATH 项目

老教程会让你把代码放到 $GOPATH/src 下，那是 GOPATH 模式，Go 1.16 起默认使用模块模式：

  • 任何目录只要有 go.mod，就是一个模块，可以放在磁盘任意位置。
  • 依赖版本记录在 go.mod，校验和记录在 go.sum，两者都应提交到版本库。
  • 新增依赖不需要手动编辑 go.mod：
go get github.com/spf13/cobra@latest   # 拉取并写入 go.mod
go mod tidy                            # 清理未使用依赖、补齐缺失依赖

go mod tidy 是最常用的维护命令，删代码后残留的依赖由它清理。

最小项目结构

单文件程序不需要结构；代码超过几百行后建议按职责分包：

hello/
├── go.mod
├── main.go              # package main，只做参数解析与装配
├── internal/
│   └── greet/
│       └── greet.go     # package greet，业务逻辑
└── greet_test.go

两个约定值得一开始就遵守：

  1. internal/ 目录下的包只能被同一模块引用，天然阻止外部项目依赖你的内部实现。
  2. main 包只做装配：解析参数、创建依赖、调用业务包，不放业务逻辑，这样业务代码可以被测试和复用。

包名与导入

package greet

import (
    "fmt"
    "strings"
)
  • 导入路径是模块名 + 目录路径，例如 example/hello/internal/greet。
  • 包名习惯用短小的单词，不用下划线或驼峰（httputil 而不是 http_util）。
  • 导入但未使用的包会编译失败，这是 Go 的硬性规则，不是警告。

常见错误与注意事项

  1. 安装后 go 命令找不到：PATH 未刷新，重开终端；Windows 检查安装路径是否加入系统变量。
  2. 在 $GOPATH/src 之外建项目却报「no required module provides package」：忘了 go mod init。
  3. 导入路径写成相对路径（如 "./greet"）：模块模式下不允许，必须用模块全路径。
  4. 导入后没使用：编译失败，删掉导入或先用 _ 占位（仅在需要副作用导入时）。
  5. 手动改 go.mod 版本号：容易与 go.sum 不一致，用 go get / go mod tidy 管理。
  6. 把 go.sum 加进 .gitignore：会导致他人构建时校验失败，必须提交。

小结

  • 安装后用 go version 验证，必要时设置 GOPROXY。
  • 每个项目先 go mod init，依赖交给 go get 与 go mod tidy。
  • go run 临时编译执行，go build 产出二进制。
  • go fmt / go vet / go test 是日常三件套。
  • internal/ 放内部实现，main 只做装配。

下一步

标签
  • Go
  • 环境搭建
  • 模块