包名冲突是Go编译器的语法级限制，唯一合法解法是显式使用import别名，需语义化命名、避免与变量同名，并确保所有调用点同步更新。
包名冲突不是路径问题，是编译器硬性限制
Go 编译器只认 package 声明的标识符，完全不看 import 路径。两个不同仓库的包，只要都声明 package utils，在同一文件里直接导入就会报 utils redeclared in this block。这不是 IDE 显示异常，也不是 GOPATH 配置错误，是编译期立刻失败的语法级冲突。
常见无效操作包括：
- 删掉其中一个包（业务需要不能删）
- 改本地
package utils为package myutils（破坏包内所有文件一致性，且其他地方仍可能引用原名） - 以为“我不调用它就没事”（只要
import了，冲突即成立）
唯一合法解法：显式加 import 别名
必须用别名打破同名绑定，写法严格：import localutils "myproject/utils"✅，import localutils" myproject/utils"❌（双引号前不能有空格）。
别名需满足：
立即学习“go语言免费学习笔记（深入）”；
- 不能是 Go 关键字（如
type、func） - 不能与当前文件已声明的变量同名（否则遮蔽包引用，运行时逻辑错）
- 避免无上下文缩写（如
u、v），尤其当文件里同时出现u.Do()和u := getUser()时无法分辨来源 - 推荐语义化命名：第三方包用作者/项目缩写（
gorilla "github.com/gorilla/utils"），本地包带上下文（local "myapp/internal/utils"），版本差异明显时含版本（grpcv2 "google.golang.org/grpc/v2"）
别名和变量名撞车会引发静默逻辑错误
这不是编译错误，代码能跑，但行为不对。典型场景：
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
import tasks "code.google.com/p/google-api-go-client/tasks/v1"
func main() {
taskapi, _ := tasks.NewClient()
for _, tasks := range tasklists.Items { // ← 这里 tasks 变量遮蔽了 tasks 包
tasks.List().Do() // ❌ 报 undefined: tasks.List
}
}
解决方式不是改变量名，而是改包别名：tsk "code.google.com/p/google-api-go-client/tasks/v1"，并全局替换所有 tasks.X() 为 tsk.X()。
重构时务必用 grep -r "tasks\." ./ 扫描调用点——IDE 重命名功能常漏掉跨文件引用。
模块路径变更不影响别名，但别名要随作用域更新
模块路径升级（如从 google.golang.org/grpc 升到 google.golang.org/grpc/v2），只需改 import 路径：import grpc "google.golang.org/grpc/v2"，别名 grpc 可保持不变。
但别名作用域仅限当前文件。同一包在不同文件中可使用不同别名（如 a "xxx" 和 b "xxx"），这本身合法，但会增加团队理解成本。建议在 internal/docs/import-rules.md 统一约定，避免 gh、gitlab、glab 混用。
最容易被忽略的是：别名一旦确定，所有调用点必须同步更新；漏掉任意一处 .X() 就会触发 undefined 错误，而这类错误往往在运行时才暴露，不是编译期拦截。
