最常见的原因是go build未在go.work所在根目录执行，go仅在该目录识别工作区，进入子目录即退回到单模块模式，导致“module xxx is not in main module”错误；须确保当前目录含go.work、所有命令统一在此执行、use路径为相对路径、删除子模块go.mod中replace、ide需正确加载工作区并匹配goflags=-mod=mod。
go.work 工作区必须在根目录激活
联合编译失败最常见的原因是 go build 没在 go.work 所在目录执行。Go 只在当前工作目录下扫描 go.work，进到 ./cmd/app 或 ./lib 里运行命令，它就自动退回到单模块模式，报错 module xxx is not in main module。
实操要点：
- 先
ls go.work确认当前目录含该文件 - 所有命令（
go build、go test、go run）统一在该目录下执行，路径用相对形式：例如go build ./cmd/app -
go work use的参数必须是相对于工作区根的路径，如./api，不能写../other/api或绝对路径 - 删掉各子模块
go.mod中的replace语句——工作区模式下它会被忽略，反而干扰本地修改同步
IDE 必须对齐 go.work 路径
VS Code 或 GoLand 显示 no module found、跳转失效、补全空白，根本不是 gopls 坏了，而是编辑器打开的“工作区”和 go.work 不一致。
常见错误操作：
- 用 “Open Folder” 直接打开整个仓库顶层目录（此时 gopls 按单模块初始化）
- 启用 Multi-root Workspace 后没关掉
Auto-add modules on open，导致每个子目录被单独识别
正确做法：
- VS Code：用
File → Add Folder to Workspace…逐个添加./main、./lib等子模块目录；再在设置里加"go.toolsEnvVars": { "GOFLAGS": "-mod=mod" } - GoLand：右键点击含
go.work的目录 →Mark Directory as → Go Module Root - 打开命令面板
Go: Toggle Logs，确认 gopls 启动时工作目录确实是go.work所在路径
go.mod 版本声明与实际 Go 二进制必须匹配
报错 go: cannot use go 1.21.6 with go 1.22 mod 不是环境没装对，而是终端当前生效的 Go 版本和项目 go.mod 里写的 go 1.22 冲突。
Go语言（Golang）1.26.0
下载
Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。
别改 go.mod 里的版本号——那是项目契约，改了可能引入不兼容语法或标准库行为变化。
应该让 Go 二进制匹配声明：
- 用
gvm use go1.22.3切换（推荐，自动写.gvmrc） - 手动切换：设
GOROOT=/path/to/go1.22.3，并确保$GOROOT/bin在PATH前置位 - 执行
go env GOROOT验证路径是否指向预期版本，避免残留软链接干扰
多个 main 包编译必须显式指定入口
项目含 cmd/app/main.go 和 cmd/cli/main.go，直接 go build 会失败，因为 Go 不允许自动推导多个入口。
正确方式只有两种：
-
go build -o bin/app ./cmd/app（推荐，明确输出名和路径） go build -o bin/cli ./cmd/cli
注意：go run . 在多 main 场景下会报错 multiple packages，不能替代 go build；也别用 go run *.go，shell 通配符展开顺序不可控，容易漏文件或误含 _test.go。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
