Go 本地启动踩坑：为什么 `go run main.go` 会报 `undefined`？

很多 Go 项目会把启动入口拆成多个文件（例如 main.go + config.go + db.go）。这时如果你用 go run main.go 启动，可能会遇到类似错误：

text 复制代码

# command-line-arguments
.\main.go:19:14: undefined: loadConfig
.\main.go:64:17: undefined: AppConfig

一句话总结：不是代码写错了，而是运行命令只编译了一个文件，导致同包其它文件没有参与构建。

（最短解决方案）

在项目目录（包含 main.go 的那个目录）执行：

bash 复制代码

go run .

1. 结论先说：命令用错了

go run main.go：只编译/运行你列出的 main.go 这一个文件 （以及它 import 的包），不会自动把同目录的 config.go、db.go 等文件编进来。
go run .：编译/运行 当前目录这个包 （同一个 package main 下的所有 .go 文件都会参与编译）。

所以当 main.go 引用了 config.go 里定义的符号（如 loadConfig、AppConfig）时，go run main.go 就会提示 undefined。

2. 发生了什么：Go 的编译单位是"包"

在 Go 里，源文件最终会组成"包（package）"。当你写：

go 复制代码

package main

只要 main.go 和 config.go 都在同一目录、且都是 package main，它们在正常构建时属于同一个包。

但是：

go run main.go 的语义是"运行我指定的这一个（或多个）文件集合"，因此它创建了一个临时构建目标（你会在报错里看到 # command-line-arguments）。
你没有把 config.go 传进去，这个临时构建目标里就只有 main.go，所以 loadConfig / AppConfig 自然不存在。

可以把它理解成下面这个对比：

目标	`go run main.go`	`go run .`
编译单位	文件列表	包（目录）
是否自动包含同目录其它 `.go`	否	是
典型报错提示	`command-line-arguments`	一般不会出现此类 undefined

3. 正确做法（推荐）

进入项目目录（包含 main.go 的目录），运行当前包：

bash 复制代码

go run .

这会自动编译当前目录下所有 .go 文件（同一个包的），包括 main.go、config.go 等。

4. 备选做法（显式指定多个文件）

如果你确实想用"指定文件"的方式运行，也可以把同包需要的文件全部写上：

bash 复制代码

go run main.go config.go

当文件数量变多（例如还有 router.go、db.go、bootstrap.go）时，这个方式会越来越难维护，所以通常不建议。

5. 常见误区

5.1 误区：同目录就一定会一起编译

不一定。

go run . / go build：以"包"为单位，会一起编译。
go run xxx.go：以"文件列表"为单位，只编译你列出来的文件。

5.2 误区：`go run main.go` 等价于 `go run .`

不等价。

只要项目后续按功能拆了多个 .go 文件（但仍在同一个 package main），go run main.go 很容易触发 undefined。

6. 快速排查 Checklist

报错是 # command-line-arguments 吗？
- 是：高度怀疑用了 go run 单文件 或者运行时文件集合不完整。
你调用的函数/类型在同目录另一个 .go 文件里吗？
- 是：优先改用 go run .。
是否把代码拆到了不同目录/不同包？
- 是：需要用 import 引入对应包，而不是依赖"同包可见"。

7. 建议命令（通用）

在项目目录执行：

bash 复制代码

go run .

如果你项目支持用环境变量指定配置文件路径（可选），通常类似这样：

powershell 复制代码

$env:BE_CONFIG_PATH = ".\\config.json"
go run .

Go 本地启动踩坑：为什么 `go run main.go` 会报 `undefined`？