Go语言replace指令必须使用以./或../开头的相对路径，绝对路径会导致vendor失败、CI报错等；本地目录需含匹配module名的go.mod文件，且import路径须与module声明一致。
replace 路径必须是相对路径，不能写绝对路径
很多人在 go.mod 里写 replace github.com/foo/bar => /home/user/mybar，结果 go mod vendor 失败、CI 构建报错、甚至本地 go build 都提示 invalid module path。Go 的 replace 不接受绝对路径——它只认相对于 go.mod 所在目录的路径。
正确写法是：replace github.com/foo/bar => ./local/bar（假设 local/bar 是项目根目录下的子目录）。
- 路径必须以
./或../开头，否则会被 Go 当作远程模块解析 - 被
replace指向的本地目录下，必须存在有效的go.mod文件（哪怕只有一行module local/bar），否则go mod tidy会清掉这条replace - Windows 用户注意反斜杠
\不能用，一律用正斜杠/或点号路径，例如./local/bar，不是.\local\bar
本地包 import 路径必须匹配 module 声明，不是文件系统路径
执行过 go mod init myorg/myapp 后，你在 main.go 里写 import "./pkg/utils" 或 import "utils"，都会报 no required module provides package。Go 模块不支持相对导入，也不认文件夹名，只认「模块名 + 子路径」。
假设你的目录结构是：
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
myapp/
├── go.mod # module myorg/myapp
├── main.go
└── pkg/
└── utils/
└── helper.go # package utils那么 main.go 中唯一合法的 import 是：import "myorg/myapp/pkg/utils"。
-
go.mod第一行的module名就是“根路径”，所有import都要从它开始拼接 - 子目录名（如
pkg/utils）只是路径片段，和包名（package utils）无关；包名只影响代码内如何调用，不影响 import 路径 - IDE 报红但命令行能编译？大概率是 VS Code/Goland 没以含
go.mod的目录为 workspace root，重启gopls或重新打开项目根目录即可
go build 和 go install 输出行为差异导致路径混淆
新手常以为 go install . 和 go build -o ./app 效果一样，结果发现命令行敲 app 找不到，或者 $GOBIN/app 跑不起来。根本区别在于：前者把二进制放 $GOBIN（需在 PATH 中），后者默认放当前目录。
-
go install要求模块路径完整，例如go install myorg/myapp/cmd/app@latest；直接go install .只在模块根且含main函数时有效 -
go build -o输出路径不自动加扩展名：Linux/macOS 下生成无后缀文件，Windows 下也生成无后缀文件（不是.exe），双击或直接运行会失败 - 跨平台构建建议统一用
GOOS=windows go build -o app.exe或GOOS=linux go build -o app，避免依赖本地环境 - CI/CD 中慎用
go install，它会尝试安装到$GOBIN，而该路径在容器中往往未配置PATH，推荐始终用go build -o显式输出
离线构建时 vendor 不等于“全量打包”
运行 go mod vendor 后发现 go build -mod=vendor 仍报 cannot find module providing package，不是 vendor 没生效，而是 vendor 机制有前提条件没满足。
go mod vendor 只打包 go list -m all 输出的模块，但 replace 指向的本地路径、带 // indirect 的依赖、以及某些私有模块的校验和缺失，都不会自动进 vendor/ 目录。
- 执行
go mod vendor后，检查vendor/modules.txt是否包含你replace的模块路径；如果没有，说明 Go 认为它不属于“可 vendored 模块” - 对
replace的本地路径，必须确保其自身有go.mod，且该go.mod已被go mod tidy正确引入主模块 - 加
-mod=vendor编译时，Go 会完全忽略网络和GOPROXY，但也会跳过go.sum校验——若你依赖的模块在go.sum中无 checksum，构建就会失败 - 真正离线可靠的方案是：
go mod download先拉全依赖到本地缓存，再go mod vendor，最后用go build -mod=readonly（而非-mod=vendor）强制只读缓存
容易被忽略的是：replace 生效与否，不看 go mod graph 输出，而要看 go list -m -f '{{.Dir}}' github.com/foo/bar 返回的路径是否指向你预期的本地目录。这是验证的唯一可靠方式。
