Go模块中禁止使用import "./xxx"，因其违反“导入路径=模块路径”原则，导致go build、go list解析失败，CI行为不一致，IDE跳转失效；合规写法是统一使用go.mod声明的完整模块路径如"github.com/user/project/cmd/server"。
Go 模块中不能用 import "./xxx"，这不是语法限制，而是模块系统设计原则被破坏的后果——它会让 go build、go list 和 IDE 跳转全部失效。
为什么 import "./cmd/server" 会编译失败或行为不一致
Go 模块要求「导入路径 = 模块路径」，而 ./cmd/server 是相对路径，没有全局唯一性，也不指向任何可解析的模块根。Go 工具链会误判当前目录为模块根，导致：
-
go: inconsistent definition of package xxx：同一包被多个不同路径导入时触发 -
cannot find module providing package ./xxx：go mod tidy完全忽略相对路径，不尝试解析 - 本地
go run .成功，但 CI 中从项目根执行go run ./subdir就报错——因为工作目录变了，./指向不同位置 - VS Code + gopls 无法跳转到该包，符号索引直接丢弃这条导入
replace 中的相对路径是合法的，但仅限右侧目标
replace 指令左侧必须是完整模块路径（如 github.com/user/utils），右侧可以是相对路径，但必须满足两个硬性条件：
- 该路径必须指向一个含有效
go.mod的目录（即它本身是一个模块） - 相对路径基于
go.mod文件所在目录计算，不是运行命令的目录 - 错误写法：
replace github.com/user/utils => ./local-fork（如果./local-fork没有go.mod或模块名不匹配，go mod tidy会直接报错invalid replace directive） - 正确写法：
replace github.com/user/utils => ../utils，前提是../utils/go.mod第一行是module github.com/user/utils
如何把错误的本地导入改成合规写法
核心不是“怎么让它跑起来”，而是“怎么让模块系统能正确定位”。步骤很明确：
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 确认项目
go.mod中的module声明，比如module github.com/yourname/project - 所有子包（
cmd/、internal/、pkg/）都按此前缀组织导入路径，例如import "github.com/yourname/project/cmd/server" - 子目录下不需要额外
go mod init，只要包文件以package xxx开头即可 -
go mod tidy不会帮你改导入语句——必须手动替换，或用gofmt -r 'import "./cmd/server" -> import "github.com/yourname/project/cmd/server"'批量处理
模块路径没注册也能用，但不能随便起名
即使项目还没推送到 GitHub，只要 go.mod 写对了模块路径，go build 就能识别本地包。但模块路径不能是 ./myapp 或 mylib 这类无效形式：
- 必须以域名或可解析路径开头（如
example.com/myapp、gitlab.internal/org/proj） - 避免用
localhost或127.0.0.1——虽然语法合法，但go get会尝试 HTTP 请求，可能超时或被代理拦截 - 路径中不要含空格或非 ASCII 字符，Windows 下尤其注意反斜杠转义问题
真正容易被忽略的点是：模块路径一旦写进 go.mod，所有下游代码、文档、CI 脚本就都依赖它；改路径不是改一行的事，而是要同步所有 import 语句和外部引用。所以初始化时就选对，比后期修复成本低得多。
