GoLand中config.yaml修改无反应，最常见原因是viper.WatchConfig()监听路径与实际配置文件路径不一致：viper默认监听工作目录（项目根），而AddConfigPath("./configs")指向子目录，需显式调用SetConfigFile("./configs/app.yaml")后再WatchConfig()，并确认GoLand运行配置中Working directory与路径匹配。
GoLand里改完config.yaml没反应，先看监听路径对不对
最常见原因是 viper.WatchConfig() 监听的路径和你实际加载的配置文件路径不一致。GoLand 默认工作目录是项目根，但你的 viper.AddConfigPath("./configs") 指向子目录，而 viper.WatchConfig() 会默认监听工作目录（即项目根），根本收不到子目录下的变更事件。
必须显式指定完整路径：viper.SetConfigFile("./configs/app.yaml")，再调 viper.WatchConfig()，viper 才会基于该路径监听。别依赖 AddConfigPath + SetConfigName 组合去触发 Watch —— 它不会自动推断最终文件位置。
- 在 GoLand 的 “Run Configuration” 里检查 “Working directory”，确保和
viper.SetConfigFile中的相对路径能对上 - 加一行日志：
viper.OnConfigChange(func(e fsnotify.Event) { log.Printf("watch event: %+v", e) })，确认事件是否真被收到 - 如果日志没输出，大概率是路径错位或监听失败，不是代码逻辑问题
air 启动就报 failed to build，别急着改 .air.toml
90% 的情况是 Go 代码本身编译失败，不是 air 配置问题。终端最后一行红字才是真相：undefined: xxx → 缺变量或函数，go build 直接跑一遍就能定位；import cycle not allowed → 循环引用，用 go list -f '{{.Imports}}' ./ 辅助排查；cannot find module providing package → go.mod 不在当前目录，air 默认从含 go.mod 的根启动，别在 cmd/api 里直接运行。
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
- 先在终端执行
go build，确认能通过再让 air 接管 -
.air.toml里root必须指向含go.mod的目录（通常是项目根），不是main.go所在目录 - Windows 用户注意：路径一律用正斜杠
/，哪怕在 PowerShell 里写.\tmp\main也会导致监听失效
改了 internal/handler/xxx.go 没反应，检查 air 的工作目录和 include_ext
air 默认只监听当前工作目录及子目录下的 .go 文件，不跨模块、不跟进符号链接、不扫描 vendor/ 或隐藏目录。如果你的 main.go 在 cmd/api/main.go，却在项目根目录运行 air，那 internal/ 下的改动根本不会被看到。
- 正确做法：进入
cmd/api/目录再运行air，或在.air.toml中显式配置watch.cwd = "cmd/api" - 想让
config.yaml或模板变更也触发构建，必须在[watch]和[build]两节都加include_ext = ["go", "yaml", "yml", "html", "tmpl"] - Linux 下 inotify 句柄数有限（默认 8192），加太多后缀容易触发
inotify limit reached，大项目建议只加真正需要 reload 的扩展名
fork/exec ./tmp/main: permission denied，权限和路径必须严格一致
这是 macOS/Linux 上最典型的执行失败，根源是生成的二进制没有执行权限，或 build.bin 路径与 build.cmd 输出路径不一致。例如 build.cmd 是 ./tmp/main，但 build.bin 写成 tmp/main 或 ./main，就会报 exec: "./tmp/main": file does not exist。
-
build.bin和build.cmd输出路径必须完全一致，比如都用./tmp/main -
tmp_dir对应目录要有写权限，执行ls -ld tmp看是否可写 - 容器内热重载必须配 bind mount + air 一起用，单纯在宿主机跑 air 再
docker build是伪热重载
真正容易被忽略的是：热重载只解决“代码改了要不要重启”，而配置热加载解决的是“配置改了要不要重新初始化组件”。两者触发时机、作用范围、并发安全要求完全不同，强行塞进一个工具里，反而更容易出状态不一致的问题。
