Go module 初始化失败主因是未在项目根目录执行go mod init或go.mod位置错误；本地包导入必须使用模块名前缀的逻辑路径而非文件路径，且internal包不可跨模块引用。
Go module 初始化失败：go.mod 不存在或路径不对
本地包无法导入，最常见原因是当前目录没启用 Go modules，或者 go.mod 不在预期位置。Go 1.11+ 默认依赖 go.mod 管理依赖，不初始化就用相对路径导入会直接报错 no required module provides package。
- 确保在项目根目录执行
go mod init example.com/myapp（模块名可自定义，但需是合法域名格式） - 本地包目录必须在项目根目录下（或其子目录），且不能位于
$GOPATH/src下（否则可能触发 GOPATH 模式，导致行为不一致） - 如果本地包在
./pkg/utils，则导入语句必须是import "example.com/myapp/pkg/utils"，而非import "./pkg/utils"—— Go 不支持文件系统路径式导入
本地包路径写错：模块名 vs 文件路径
Go 导入路径不是文件路径，而是模块内逻辑路径。即使包在 ./internal/log，只要 go.mod 中模块名为 example.com/myapp，就必须用 import "example.com/myapp/internal/log"。
- 检查
go.mod第一行：如为module github.com/user/project，所有本地包导入都必须以该前缀开头 - 不要在导入路径中包含
../或.，这类写法在 Go 中非法 - 如果本地包放在
./vendor/下，也不应手动导入；go build会自动从 vendor 解析，前提是已运行go mod vendor
使用 replace 替换本地开发中的依赖包
当你正在同时开发主项目和一个本地库（比如 github.com/user/lib），又不想发布新版本，可以用 replace 指向本地路径，让构建时加载未发布的修改。
replace github.com/user/lib => ../lib
-
replace必须写在go.mod文件中，且路径../lib是相对于go.mod所在目录的绝对或相对路径 - 执行
go mod tidy后，go.sum会记录替换后的校验值，但不会把本地代码打包进模块 - 注意：CI 环境通常禁用
replace，部署前建议临时注释掉并验证是否仍能拉取远程版本
internal 包被意外导出：跨模块引用失败
放在 internal/ 目录下的包默认只能被同一模块内代码导入。如果另一个本地模块（比如 example.com/cli）试图导入 example.com/myapp/internal/config，会报错 use of internal package not allowed。
立即学习“go语言免费学习笔记（深入）”；
- 这不是 bug，是 Go 的显式封装机制 —— 把不该暴露的实现细节锁死在模块边界内
- 若确实需要共享，应将这部分代码移出
internal/，放到独立的公共子模块（如example.com/myapp/config），并在go.mod中保持统一模块名 - 别用符号链接绕过
internal限制，Go 在解析时会检查真实路径，符号链接无效
go.mod 的模块名与实际目录结构的映射关系，后续所有 go build、go test 都会连锁失败。
