应执行go mod init example.com/myapp初始化模块，确保在项目根目录操作且go111module=on，再运行go mod tidy拉取依赖；避免将项目置于$gopath/src下。

go build 报 cannot find main module 怎么办

这是最典型的「没开模块」症状，不是路径错、不是网络问题，就是 go.mod 根本不存在或没被识别。Go 1.16+ 默认强制走模块模式，go build 一执行就找 go.mod，找不到直接报错。

• 进项目根目录，运行 go mod init example.com/myapp（模块名必须带域名格式，别写 myapp）
• 模块名不一定要能访问，但得符合规范：不能纯数字开头、不能含空格/中文、推荐用反向域名（如 github.com/yourname/project）
• 初始化后会生成 go.mod 和 go.sum，此时再跑 go build 就能识别主模块了
• 如果之前在 $GOPATH/src 下建的项目，现在必须移出来——模块模式下，$GOPATH/src 会被无视

GO111MODULE=off 导致 go mod 失效

即使你手动写了 go.mod，只要 GO111MODULE=off，Go 就当它不存在，继续 fallback 到旧式 GOPATH 查找逻辑，自然报 no required module provides package。

Go语言（Golang）1.26.0

Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。

下载

• 检查当前设置：go env GO111MODULE，输出 off 就是问题根源
• 永久关闭旧模式：go env -w GO111MODULE=on
• 顺手清理掉 shell 配置文件（~/.bashrc、~/.zshrc）里所有 export GO111MODULE=off 的行
• 重启终端或执行 source ~/.zshrc（按你实际 shell 类型），否则环境变量不生效

本地包 import 失败：no matching versions for query "latest"

模块模式下，import "utils" 这种写法会被当成远程包解析，而不是读当前目录下的 utils/ 子目录——Go 不认相对路径，也不自动发现本地子模块。

• 先确保 utils/ 目录下有独立的 go.mod（哪怕只有一行 module utils）
• 在主项目的 go.mod 里加 replace utils => ./utils（路径必须相对于主 go.mod 所在位置）
• replace 行不能用绝对路径，也不能漏掉 ./ 前缀，否则 go mod tidy 会把它删掉
• 加完 replace 后立刻运行 go mod tidy，否则依赖不会被拉入 go.mod

go mod tidy 没反应或报错网络超时

go mod tidy 不只是补依赖，它还会校验 checksum、下载缺失模块、清理未引用项。如果卡住或报 Get "https://..." dial tcp: i/o timeout，大概率是代理或源配置问题。

• 国内建议设代理：go env -w GOPROXY=https://goproxy.cn,direct
• 如果公司内网禁外网，可设私有代理或用 direct 模式（需确保所有依赖都能直连）
• 偶尔缓存损坏会导致 tidy 失效，可清缓存：go clean -modcache，再重试
• 注意：go mod tidy 必须在有 go.mod 的目录下执行，且当前目录要能被识别为主模块（即 go list -m 能返回模块名）

真正容易被忽略的是模块路径和 replace 的路径一致性——go.mod 里的 module 声明、import 语句中的路径、replace 右侧的本地路径，三者必须能对齐，差一个 ./ 或多一层目录，都会让依赖链断掉。

golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！