go语言跨目录调用失败的根本原因是import路径必须为模块名拼接子目录的绝对路径，而非文件系统相对路径；go.mod必须置于项目逻辑根目录，且ide需正确识别模块边界，否则将报cannot find package或import path does not begin with hostname。
跨目录调用失败：先确认模块根目录和 go.mod 位置
GoLand 中跨目录调用报错（比如 cannot find package "xxx" 或 import path does not begin with hostname），90% 是因为 go.mod 没放在项目逻辑根目录，或者 IDE 没识别到模块边界。Go 不靠文件夹路径推断包路径，只认 go mod init 声明的模块名 + 目录相对关系。
实操建议：
-
go.mod必须在你整个项目最外层目录（即所有子包都位于其下的那个目录），且该目录名不重要，模块名由go mod init your-module-name决定 - 在 GoLand 终端中执行
go mod init github.com/yourname/project（推荐用类域名格式，避免空格和下划线） - 执行后检查
go.mod是否生成，且内容含module github.com/yourname/project - 重启 GoLand 或右键项目根目录 →
Reload project，让 IDE 重新解析模块结构
import 路径写错：不是文件系统路径，而是模块路径 + 子目录
你在 main.go 里写 import "model" 肯定失败——Go 的 import 路径是模块名拼接子目录，不是当前文件夹名。比如模块名是 github.com/yourname/project，而 model 文件夹在项目根目录下，那正确 import 就是 import "github.com/yourname/project/model"。
常见错误现象：
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
- IDE 提示 “Unresolved reference”，但
go build却成功：说明 IDE 缓存没更新，执行File → Reload project from disk - 运行时报
no required module provides package：go.mod里没声明该路径，或路径大小写/拼写与实际目录不符（Linux/macOS 区分大小写） - 想用短名如
"model"：Go 不支持裸路径 import，必须带完整模块前缀
想限制包可见性？用 internal/，但别放错位置
internal/ 不是命名约定，是 Go 编译器硬性规则：任何包路径含 /internal/ 片段时，只有其父目录（或祖先目录）同属一个模块，才能 import。它不解决“怎么调用”，而是防止被外部模块误引用。
使用场景和易踩坑点：
- 把不想被其他项目直接依赖的代码（如数据库封装、领域模型实现）放进
internal/repo或internal/domain -
internal必须是路径中的一级目录，比如github.com/yourname/project/internal/repo合法，但github.com/yourname/project/repo/internal不生效 - 测试文件（
*_test.go）属于同包，可直接访问internal下的非导出符号；但xxx_test包（独立包）不能 importinternal - 错误提示永远是
use of internal package not allowed，且是编译期 fatal error，不是 warning
多命令或多服务项目：别在根目录塞多个 main 包
当你有 cmd/api/main.go 和 cmd/cli/main.go 时，不要让它们都 import 同一个 github.com/yourname/project/internal/xxx 然后各自构建——这没问题；但若试图让 cmd/api 直接 import cmd/cli，就会触发循环依赖或 internal 误用。
正确做法：
- 所有可执行入口统一放在
cmd/下，每个子目录一个main包 - 共享逻辑全部上提到
internal/或pkg/（后者用于明确对外复用） - 如果真要拆成独立发布模块（如 auth、payment），就在
modules/auth/go.mod单独初始化，但需确保根项目用replace或require显式管理版本 - GoLand 中右键
cmd/api→Run即可单独构建该命令，无需全局go run ./...
go.mod 的 module 声明、目录相对于模块根的位置、以及首字母大小写的导出规则。其余都是干扰项。
