根本原因是模块未正确初始化或本地依赖路径与go.mod中声明的模块路径不一致；需在项目根目录执行go mod init，运行go mod tidy补全依赖，并避免误放项目于$GOPATH/src下。
go mod 是当前 Go 项目依赖管理的唯一事实标准，GO111MODULE=on 已是默认行为（Go 1.13+），不再需要手动设置或依赖 GOPATH 工作区来组织项目。
go mod init 后为什么 go build 报错找不到包？
常见现象是执行 go build 时提示类似 cannot find package "github.com/some/lib" 或 no required module provides package。
根本原因是：模块未正确初始化，或本地依赖路径与 go.mod 中声明的模块路径不一致（尤其在迁移旧项目或复制代码时）。
- 确保在项目根目录执行
go mod init example.com/myapp，模块路径必须唯一且符合域名反向约定（如github.com/yourname/project） - 如果已有
import语句引用了未声明的远程包，运行go mod tidy自动补全依赖并下载 - 避免手动编辑
go.mod中的replace或exclude，除非你明确知道副作用——它们会绕过版本解析，容易导致 CI 环境构建失败 - 检查是否误把项目放在
$GOPATH/src下：Go Modules 模式下，GOPATH不再影响模块查找逻辑，放错位置反而可能触发旧式 GOPATH 模式（尤其当目录名匹配某个已知 import 路径时）
cmd/internal/pkg 这类目录结构真有必要吗？
不是语法强制，但它是工程可维护性的分水岭。没有明确边界，internal 包会被外部模块意外导入，pkg 和 cmd 混在一起则难以复用和测试。
立即学习“go语言免费学习笔记（深入）”；
-
/cmd只放main.go，每个子目录对应一个独立二进制（如/cmd/api、/cmd/cli），便于多入口构建 -
/internal下的包只能被本模块导入，Go 编译器会拒绝跨模块引用，这是天然的封装屏障 -
/pkg用于导出给其他项目复用的公共能力（如pkg/auth、pkg/db），它的 API 必须稳定，需配套单元测试 - 别为了“规范”而堆砌目录：如果项目只有单个服务且无复用意图，
/cmd/main.go+/internal/handler就足够；过度分层反而增加跳转成本
go run 和 go build 的输出路径为什么不一样？
go run 编译后直接执行并清理临时文件，go build 默认输出到当前目录（除非指定 -o）。这看似琐碎，实则影响发布流程和调试一致性。
-
go run main.go不生成可执行文件，适合快速验证逻辑，但无法用strace或perf分析启动行为 -
go build -o ./bin/app显式指定输出路径，避免污染源码目录；配合-ldflags注入版本信息时必须用go build - CI 构建中禁用
go run：它不保证产物可复现，且无法传递-race或-gcflags等底层编译参数 - 注意
go build默认不递归编译/cmd/*下所有入口——要批量构建，得写脚本遍历或用go install（需配置GOBIN）
本地开发时 go get 总超时或 404？
国内直连 proxy.golang.org 基本不可行，但盲目设 GOPROXY 也可能引入缓存陈旧、校验失败等问题。
- 推荐组合：
export GOPROXY=https://goproxy.cn,direct——direct表示对私有仓库（如公司内网 Git）走直连，避免代理拦截 - 若使用私有模块（如
git.example.com/internal/lib），在go.mod中加replace前，先确认该仓库支持 HTTPS + git 协议，且go能正常git clone -
go clean -modcache可清除本地模块缓存，解决因代理中途切换导致的 checksum mismatch 错误 - 不要在
.bashrc里硬编码GOPROXY：不同项目可能需不同策略（如开源项目用官方 proxy，内部项目用 Nexus），应按项目目录设置或用direnv
真正容易被忽略的是：模块路径（module 行）一旦写入 go.mod 并推送到远程仓库，就不能随意修改——否则所有依赖它的下游项目都会 break。哪怕只是从 example.com/v2 改成 example.com/api/v2，都算不兼容变更。
