GoLand 默认仅运行单个 .go 文件，导致多文件项目因依赖未编译而崩溃；需通过配置「Run Kind = Package」并指定模块根路径，让 IDE 调用 go run . 完整构建 main 包所有源文件。
goland 默认仅运行单个 `.go` 文件，导致多文件项目因依赖未编译而崩溃；需通过配置「run kind = package」并指定模块根路径，让 ide 调用 `go run .` 完整构建 main 包所有源文件。
在 GoLand 中运行一个含多个 .go 文件的 Go 项目（如 main.go、handler.go、utils.go），不能仅点击 main.go 旁的绿色三角形——这会触发 go run main.go，而 Go 工具链将忽略同目录下其他 package main 文件，导致 undefined: xxx 错误（例如函数或变量未定义）。
✅ 正确做法是：让 GoLand 执行等效于终端中 go run . 的命令，即自动扫描当前目录下所有属于 main 包的 .go 文件（排除 _test.go），统一编译运行。具体配置步骤如下：
1. 配置运行目标为「Package」
- 点击右上角运行配置下拉箭头 → Edit Configurations…
- 在弹出窗口中，点击左上角 + → 选择 Go Build
- 设置关键字段：
-
Name: 可自定义（如
Run Project） - Run kind: ✅ 选择 Package（不是 Directory 或 File）
-
Package: ✅ 填写你的模块根目录路径（即
go.mod所在目录的相对路径，通常为.或留空；若项目位于~/myapp，此处填./myapp或直接.） -
Working directory: ✅ 设为项目根目录（如
$ProjectFileDir$） - 其他选项保持默认即可
-
Name: 可自定义（如
⚠️ 注意：
Run kind = Package是核心。它对应 Go CLI 的go run <package-path></package-path>模式，当<package-path></package-path>为.时，等价于go run .，IDE 将自动解析模块路径并加载全部main包文件。
2. 验证项目结构合规性
确保以下前提成立，否则配置无效：
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
- 所有参与运行的
.go文件顶部声明package main（不可为package utils或其他） - 项目根目录存在有效的
go.mod文件（推荐新建项目时直接选 Go Module 类型） -
无重复的
func main()—— 整个项目只能有一个main()函数（通常在main.go中） - 所有文件位于同一目录（或按 Go Modules 规则组织子包，但主程序入口必须可被
.路径解析）
3. 示例：典型多文件项目结构
myapp/ ├── go.mod # 必须存在 ├── main.go # package main + func main() ├── handler.go # package main ├── utils.go # package main └── config.yaml # 非 Go 文件，不影响编译
此时在 GoLand 中配置 Package = . 即可完整运行整个项目。
4. 常见陷阱与解决方案
| 现象 | 原因 | 解决方案 |
|---|---|---|
| 运行按钮灰色 / 提示 “No SDK configured” | GOROOT 未正确指向 Go 安装根目录（如 /usr/local/go），或未重启 IDE |
进入 Settings → Go → GOROOT，手动选择含 src/、pkg/、bin/ 的根目录 → 必须重启 GoLand
|
报错 main module does not contain package
|
当前目录无 go.mod，或 Package 字段填了错误路径（如 ./cmd/app 但该路径下无 main.go） |
确保在模块根目录操作；Package 填 . 或留空（GoLand 2025+ 版本自动识别） |
import "xxx" 标红或 cannot find package
|
Go Modules 未启用，或 GOPROXY 未配置 |
Settings → Go → Go Modules → 勾选 Enable Go modules integration，Proxy 填 https://goproxy.cn,direct
|
终端 go run . 成功，但 GoLand 仍失败 |
IDE 缓存未刷新 | 右键项目根目录 → Reload project（非 Sync） |
? 终极验证方式：
在项目根目录打开 GoLand 内置 Terminal，执行：
go run .
若成功输出，说明项目结构和环境无问题；此时再应用上述 Package 配置，即可一键运行。
遵循以上配置，你就能彻底告别 undefined 错误，真正实现 GoLand 对多文件 Go 项目的“一键全量运行”。
