go工作区（go.work）仅在严格满足路径、命令和作用域约束时生效：必须置于所有模块共同父目录，命令需在根目录执行或显式指定-workfile，ide需手动重载gopls。
Go 工作区（go.work）不是“配好就能用”的开关，它只在你严格遵循路径、命令和作用域三重约束时才真正生效。最常失效的原因不是不会写，而是执行位置错了、路径写绝对了、或 IDE 没重载。
go.work 文件必须放在所有模块的共同父目录下
这个目录不能是某个子模块内部，也不能是家目录或混杂其他项目的通用 workspace。一旦放错，go 命令根本不会识别它——它只从当前目录开始向上找，且只认第一个 go.work，不递归、不跳级。
- ✅ 正确做法：新建空目录
myproject/，把./api、./core、./shared全部作为平级子目录放进去，再在myproject/下运行go work init - ❌ 错误示例：
myproject/api/go.work会报go: cannot use work file ... because a nested work file exists；~/go/src/myproject/go.work则被完全忽略 - ⚠️ 注意：
go.work不支持跨父目录引用，比如../shared/core是非法的，必须软链或调整结构使其变成./shared/core
replace 必须用 ./ 开头的相对路径，且仅对工作区全局生效
go.work 中的 replace 和 go.mod 里的不是一回事。前者优先级更高、影响所有被 use 的模块，且 Go 明确禁止绝对路径——写错直接构建失败。
- ✅ 合法写法只有：
replace example.com/core => ./core（路径相对于go.work所在目录） - ❌ 绝对路径如
/home/user/project/core或上级路径如../core都会触发replace directive must not be absolute - ⚠️ 关键点：它不改任何
go.mod，也不自动刷新缓存；加完replace后，必须进对应模块目录手动跑go mod tidy，否则import仍按旧require去拉远程版本
go run / go test 默认不读 go.work，必须显式启用
这是最隐蔽的坑：你在 ./api 目录下敲 go run main.go，工具链完全无视 go.work，照常解析 ./api/go.mod —— 它不会自动上溯找工作区，也不会加载本地 replace。
- ✅ 推荐做法：始终在
go.work所在根目录执行命令，例如go run ./api或go test ./core - ✅ 替代方案：在子目录中加参数显式指定，如
go run -workfile ../go.work ./main.go（注意路径是相对于当前目录） - ✅ 快速验证是否生效：
go list -m all输出中出现v0.0.0-00010101000000-000000000000 => ./core这类带=>的行才算成功
VS Code + gopls 必须手动重载才能识别工作区
编辑器不会自动感知 go.work 变更。即使文件存在、命令行已生效，VS Code 状态栏仍可能显示 Module: api 而非 Workspace: api+core，导致跳转错乱、补全缺失、import 报红。
- ✅ 正确打开方式：在 VS Code 中打开整个
myproject/文件夹（不是只打开./api子目录） - ✅ 强制重载语言服务器：按
Ctrl+Shift+P→ 输入Go: Restart Language Server→ 回车 - ✅ 看右下角状态栏：应显示类似
Workspace: api+core (go1.21)；若仍是Module: api，说明gopls根本没读到go.work - ⚠️ 注意：
.vscode/settings.json里无需额外配置，但要确认没写死"go.useLanguageServer": false这类禁用项
工作区模式本质是本地开发视图，不是构建规范。CI 脚本、Docker 构建、甚至 go install 都默认忽略它——上线前务必退回到单模块模式，用 go mod vendor 或 -mod=mod 显式控制依赖来源。别让本地便利污染构建确定性。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
