必须在go.work所在根目录执行命令，子目录中go退化为单模块模式，导致“module not in main module”错误；go work use路径须相对根目录且无replace冲突，ide需正确配置工作区路径。
go work init后命令仍报“module not in main module”
这不是配置失效，而是根本没进入工作区上下文。Go 工具链只在当前目录存在 go.work 文件时才启用 workspace 模式，不会向上查找或自动识别子目录。
常见错误现象：
- 在
./service-a目录下执行go run main.go，报错module xxx is not in main module -
go work edit -print报no work file found
实操建议：
- 必须在
go.work所在的根目录下运行所有go命令，比如go build ./cmd/app或go test ./... - 确认当前路径下真实存在
go.work文件（不是go.work.bak或隐藏文件） - 不要用
go build ./试图批量构建多个模块——workspace 不支持该写法，会退化为单模块解析
go work use 添加了模块，但 import 仍解析不到本地代码
原因通常是路径未被真正纳入解析链，或者被残留的 replace 指令劫持。go.work 的 use 和 replace 有明确优先级关系，混用极易出问题。
实操建议：
- 删掉所有子模块
go.mod中的replace行——如果已用go work use ./lib，再留replace example.com/lib => ../lib会导致冲突报错：cannot use replaced module in workspace -
go work use的路径必须是相对于go.work所在目录的，且目标路径下必须有有效的go.mod；不能写../lib或绝对路径 - 执行
go work edit -json查看当前生效的use列表，确认路径拼写和层级无误
VS Code / GoLand 里 import 红线、跳转失效
IDE 并不自动读取 go.work，尤其在多根工作区或旧项目迁移时，gopls 很可能按单模块逻辑初始化，导致 “no module found” 日志反复出现。
实操建议：
- VS Code：不要用 “Open Folder” 打开整个仓库根目录；改用 “File → Add Folder to Workspace…” 逐个添加子模块目录，并在设置中显式配置
"go.toolsEnvVars": { "GOFLAGS": "-mod=mod" } - GoLand：右键点击含
go.work的目录 → “Mark Directory as → Go Module Root”，然后检查 “Go → GOPATH” 设置是否指向该目录 - 打开命令面板（
Ctrl+Shift+P），运行 “Go: Toggle Logs”，确认 gopls 启动时的working directory确实是go.work所在路径 - 禁用 GoLand 的 “Auto-add modules on open”，否则它会绕过
go.work单独初始化每个子目录
CI/CD 中 go build 失败，本地却正常
这是最易被忽略的点：CI 环境默认不识别 go.work，也不预设 workspace 上下文。所有 CI 脚本都应视为“无工作区环境”运行。
实操建议：
- 上线构建必须退回到单模块模式：进每个子模块目录，单独执行
go mod tidy && go build - 避免在 CI 中使用
go work相关命令；它仅用于本地开发协同，不是构建标准 - 若需复现本地依赖状态，可用
go mod vendor提前拉取并锁定全部依赖，再关闭GO111MODULE或设-mod=vendor - CI 配置中显式指定 Go 版本（如
setup-go@v4），避免因系统默认 Go 版本与go.mod中声明不一致而失败
go.work 文件本身，而在执行路径、IDE 初始化方式或构建环境假设上。只要守住“workspace 是一个 shell 上下文，不是全局开关”这个前提，绝大多数问题都能快速定位。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
