答案：本地包必须声明合法模块路径且import路径严格匹配，replace仅重定向源码位置而不改变import语义。1. 子模块需独立go.mod并声明module路径（如local/myproj/utils）；2. import必须用该完整路径，不可用目录名或短名；3. replace仅用于开发期将模块路径映射到本地目录，要求左右路径完全一致；4. ci中须清除replace或改用绝对路径，否则构建失败。
本地包路径必须匹配模块路径，否则 import 失败
Go 不允许用任意路径 import 本地包。当你在单仓库里拆出多个子模块（比如 internal/utils、cmd/api），它们的 import 路径不是文件系统相对路径，而是基于各自 go.mod 中声明的 module 路径拼出来的。
常见错误现象：import "utils" 报错 no required module provides package "utils" —— 因为 Go 只认模块路径，不认目录名。
- 如果子模块
utils的go.mod写的是module example.com/myproj/utils，那其他地方必须用import "example.com/myproj/utils" - 不能靠
replace把它“映射”成短名，replace只改源码位置，不改 import 路径语义 - 模块路径必须全局唯一，哪怕只在本地开发，也建议用形如
local/myproj/utils这种不会和公网冲突的前缀
单仓库多模块必须各自有 go.mod，且不能嵌套
Go 不支持“一个 go.mod 管理多个子模块”。每个子模块（即希望被独立 import 或版本发布的代码单元）都得有自己的 go.mod 文件，且不能位于另一个模块的 go.mod 目录树内部 —— 否则 go build 会报 go: inconsistent module path。
使用场景：你想把 api、storage、cli 拆成可单独测试/复用的模块，又不想开多个 Git 仓库。
- 结构示例：
./go.mod（根模块，通常只放main）、./api/go.mod、./storage/go.mod，三者平级 - 根模块若要 import 子模块，得先在根
go.mod里加replace local/myproj/api => ./api，再import "local/myproj/api" -
go mod tidy在根目录执行时，不会自动拉取子模块依赖；得进./api目录单独go mod tidy
replace 是临时调试手段，不是模块定义方式
replace 常被误当成“让本地包可 import”的标准做法，但它实际只做两件事：重定向源码下载位置、绕过版本校验。它不参与模块路径解析，也不改变 import 语句本身是否合法。
容易踩的坑：
- 写了
replace local/myproj/utils => ./utils，但没在./utils/go.mod里声明module local/myproj/utils→ import 仍失败 - CI 构建时没同步
replace行，导致构建环境找不到本地路径 → 构建失败 -
replace不会被go list -m all列为直接依赖，间接依赖逻辑可能意外跳过
go.sum 和 indirect 依赖在本地模块中容易混乱
本地模块之间互相引用时，go.sum 会记录每个模块的 checksum，但 indirect 标记容易误导人 —— 它只表示“该模块未被当前 go.mod 的 require 显式列出”，不代表它不重要。
性能与兼容性影响：
- 子模块升级后，根模块不
go mod tidy，go build可能用旧版 checksum 编译，运行时报符号缺失 - 本地模块若含
replace，go mod verify会跳过校验，但go mod download -json仍按原始路径查 checksum，可能不一致 - 多人协作时，有人删了
replace行但没删go.sum对应条目，go mod tidy不会自动清理，导致冗余或冲突
真正定义本地包可被 import 的，只有两件事：模块路径声明 + 正确的 replace 或 go mod edit -replace 配置。其余都是辅助验证或构建约束。路径写错、go.mod 缺失、或 replace 范围错配，任何一个环节断掉，import 就会静默失败 —— 而不是报错提示你哪里漏了。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
