go项目启动失败主因是当前目录非模块根目录，必须在含go.mod的目录执行go run .或go run cmd/xxx，确保module声明正确且main.go位于合法路径。

Go项目启动失败，90%是因为当前目录不是模块根目录。直接在子目录或空文件夹里执行 go run main.go，几乎必然报 main module does not contain package——这不是代码写错了，而是 Go 根本没找到你的模块上下文。

go run 报 “main module does not contain package” 怎么办

这个错误只说明一件事：Go 不知道该从哪个模块加载代码。它不看你有没有 main.go，只认 go.mod 文件所在位置。

• 用 pwd 确认当前路径，必须是包含 go.mod 的目录（即模块根目录），不是 cmd/myapp/ 或 internal/ 这类子目录
• 如果 go.mod 不存在，别硬跑，先执行 go mod init github.com/yourname/projectname ——注意模块名别写成 ./project 或空字符串
• 如果项目是从 Git 克隆的但漏了 go.mod，go mod init 是唯一合法起点，不要试图靠 go build 强行绕过
• go run main.go 仅在 main.go 位于当前目录时有效；若它在 cmd/api/main.go，就得写 go run cmd/api，不能写 go run cmd/api/main.go（后者会忽略模块路径）

go.mod 文件第一行写错会导致整个模块失效

go.mod 不是配置文件，它是模块身份声明。第一行 module 指令出错，后续所有依赖解析都会崩。

Go语言（Golang）1.26.0

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

下载

• 必须以 module github.com/username/repo 开头，不能是注释、空行、或本地路径如 module myapp
• 模块名要和你未来 import 语句里的路径一致，比如 import "github.com/username/repo/pkg/log"，否则 go list -m all 会显示解析异常
• 如果模块名写成 module ./myapp，go mod tidy 会直接失败并提示 no required module provides package
• 初始化后立刻运行 go list -m all，输出里应该有你自己的模块名，且版本显示为 (devel)，否则模块未被正确识别

main.go 放错位置会让 go build 完全找不到入口

Go 不按文件名找入口，而是按包名 + 目录结构推导。放错位置，go run . 就会报 no Go files in current directory。

• 单命令项目：把 main.go 放在模块根目录，包声明为 package main，这是最简且兼容性最好的做法
• 多命令项目（如 CLI + server）：按 cmd/cli/main.go 和 cmd/server/main.go 组织，每个 main.go 都是独立的 package main，构建时用 go run cmd/cli 或 go build cmd/cli
• 绝对不要把 main.go 放进 pkg/、internal/ 或 lib/——这些目录下 Go 工具默认不扫描可执行入口
• 根目录下除了 go.mod、go.sum 和 main.go（或 cmd/），不应放业务逻辑代码；否则 IDE 和 CI 脚本容易误判入口点

GO111MODULE=on 但 still no go.mod？检查 GOPATH 干扰

即使启用了模块模式，旧式 GOPATH 配置仍可能让 Go 工具链降级回 GOPATH 模式，导致 go mod init 无效。

• 运行 go env GO111MODULE，确认输出是 on；如果是 auto，在非 GOPATH/src 下可能不触发模块模式
• 执行 go env GOPATH，如果输出的是类似 /home/user/go 这种传统路径，且你当前不在 $GOPATH/src/... 下，就可能触发冲突
• 临时禁用干扰：GOPATH= go mod init github.com/yourname/project（前面加个空 GOPATH= 可绕过现有值）
• 长期建议：不要 export GOPATH，除非你明确需要 go install 输出到特定 bin/ 目录；现代 Go 项目基本不需要手动设 GOPATH

真正卡住人的地方，往往不是语法或逻辑，而是模块路径和构建上下文这两个隐形开关没对齐。每次执行前，花 3 秒看一眼当前目录、go.mod 是否存在、go env GOPATH 是否干扰了查找路径，比反复改代码更省时间。

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