Go 1.22+ 已彻底告别强制 GOPATH，go mod 是默认且唯一推荐的依赖管理模式；必须确保 go version ≥ 1.22 且 GO111MODULE=on，项目应置于任意路径并用 go mod init 初始化，禁用 GOPATH 路径约束。
Go 1.22+ 已彻底告别强制 GOPATH 时代，go mod 是默认且唯一推荐的依赖管理模式。只要 go version 输出 ≥ 1.22，就别再手动设 GOPATH 或把代码塞进 $GOPATH/src —— 那套老路径规则不仅多余，还会干扰模块解析，引发 cannot find package 报错。
验证 Go 安装并确认模块模式已启用
打开终端，执行：
go version
输出应类似 go version go1.22.5 darwin/arm64 或更高。接着运行：
go env GO111MODULE
结果必须是 on（不是 auto 或空）。若为 auto，说明某些旧项目残留配置干扰了全局行为，执行以下命令强制开启：
立即学习“go语言免费学习笔记（深入）”；
go env -w GO111MODULE=on
-
GO111MODULE=auto在有go.mod文件时才启用模块，没文件就退化回 GOPATH 模式 —— 这正是很多“本地能跑、CI 报错”的根源 - Windows 用户注意：PowerShell 中
go env -w写入的是用户级环境变量，CMD 可能读不到，建议统一用 PowerShell 或 WSL - 国内用户务必同步设置代理，否则
go get或go mod download会卡死：
go env -w GOPROXY=https://goproxy.cn,direct
VS Code + Go 插件：只装这 4 个核心工具
VS Code 安装官方 Go 扩展（由 Go Team 维护）后，首次打开 .go 文件会弹出工具安装提示。**不要点「全部安装」**—— 很多工具（如 gocode、godef）已废弃，装了反而冲突。只需确保以下 4 个可用：
-
gopls：语言服务器，提供跳转、补全、诊断（必须） -
go：Go CLI 本身（已存在，无需额外装） -
dlv：调试器（调试时才需要，可延后装） -
gofumpt：格式化工具（比gofmt更严格，推荐）
如果提示 gopls 启动失败，大概率是代理没生效或模块缓存损坏，先运行：
go clean -modcache && go mod download
初始化项目：绕过 GOPATH 的标准流程
新建任意目录（比如 ~/projects/myapi），在该目录下执行：
go mod init myapi
注意：myapi 是模块路径（module path），**不是文件夹名**，也不必带域名。它只用于内部 import 解析，只要全局唯一即可。常见错误包括：
- 写成
go mod init github.com/you/myapi—— 没错，但没必要；私有项目用简单名字更安全 - 在已有
go.mod的父目录里再go mod init—— 会导致嵌套模块，go build会报main module is not in GOPATH - 模块名含大写字母或空格 ——
go工具链不支持，会静默失败
写完 main.go 后，直接 go run . 即可启动，无需 go install 或进入 src 目录。
HTTP 服务快速验证：避免端口被占和路由陷阱
用标准库启动服务时，别直接写 http.ListenAndServe(":8080", nil)。常见问题：
- 端口 8080 已被占用（Chrome 插件、Docker、其他 Go 进程都可能抢走）→ 改用随机空闲端口：
ln, err := net.Listen("tcp", ":0")
- 没注册任何 handler，访问
/返回 404 → 至少加一个http.HandleFunc("/", ...)，或明确传入nil表示使用http.DefaultServeMux - 忘记
log.Fatal(err)→ 程序静默退出，你以为跑起来了，其实根本没监听
最小可运行片段：
package main
import (
"log"
"net/http"
)
func main() {
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("OK"))
})
log.Fatal(http.ListenAndServe(":8080", nil))
}
运行后 curl localhost:8080 应返回 OK。如果浏览器打不开，先 curl -v http://localhost:8080 看底层响应，排除前端代理或防火墙干扰。
真正麻烦的从来不是装软件，而是不同 Go 版本对 go.mod 语义的微小差异（比如 go 1.21 和 go 1.22 对 // indirect 标记的处理），以及团队里有人还在用 go get 替代 go mod tidy。这些细节不显眼，但会在 CI 构建时集中爆发。
