根本原因是go无法自动推断模块路径，必须显式指定与import路径一致的module名；需清理vendor、正确配置goproxy，并统一所有import为完整模块路径。
go mod init 为什么报 “cannot determine module path”
根本原因是 Go 不知道该给模块起什么名字，它不会猜，尤其当项目没配 Git 或路径不规范时。别依赖自动推断，直接显式指定：go mod init github.com/your-org/your-project。模块名必须和所有 import 语句开头的路径一致——比如代码里写了 import "github.com/your-org/your-project/handler"，那 go.mod 第一行就必须是 module github.com/your-org/your-project。用本地路径（/home/user/proj）、相对路径（./proj）或随意起名（myapp）都会导致后续 go build 找不到包。
vendor 目录残留让 go build 看不见 go.mod
旧项目如果留着 vendor/ 目录，go build 默认仍会优先读它，完全绕过 go.mod 和 GOPROXY。这不是 bug，是 Go 的兼容策略。迁移前必须先清理：rm -rf vendor。之后再跑 go mod tidy，确认依赖都进了 go.mod；想重建 vendor，再执行 go mod vendor。注意：go mod vendor 不会保留你之前手动 patch 过的包——如果用了 fork 分支，得先在 go.mod 里写好 replace，比如：replace github.com/some/lib => github.com/your-fork/lib v0.0.0-20230101000000-abc1234，再 go mod vendor。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
GOPROXY 配置不对，CI 构建就卡在 go get -u
Go 1.13+ 默认启用 GOPROXY=https://proxy.golang.org,direct，国内访问不了 proxy.golang.org，CI 就会超时或报 checksum mismatch。不是网络问题，是代理没切对。必须在 CI 脚本开头或环境变量里显式设置：go env -w GOPROXY=https://goproxy.cn,direct。同时关掉校验干扰：go env -w GOSUMDB=off（仅限内网可信环境）或配 GOPRIVATE=git.internal.company.com/* 处理私有仓库。漏设 GOPROXY 的后果是：本地能过，CI 每次都失败，且错误信息只显示 “timeout” 或 “no such file”，根本看不出是代理问题。
import 路径没改完，编译就报 cannot find module
GOPATH 时代允许写 import "utils" 或 import "server/router"，Modules 下这些路径全失效。只有两种 import 是合法的：./xxx（当前目录子包）和完整模块路径（如 import "github.com/your-org/your-project/utils"）。用 grep -r 'import "' . --include="*.go" | grep -v '^\.' | grep -v '"' | grep -v '/' 快速扫出疑似短路径导入，逐个核对修正。特别注意测试文件（*_test.go）里可能藏着未被主逻辑引用的包，它们的 import 也得改，否则 go test 一样失败。改完后，go list -m all 应该只列出你声明的模块和它的依赖，没有 unknown 或空路径。
import、漏删一个 vendor/、CI 里少设一行 GOPROXY，都会让构建行为在本地和远程不一致。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
