goland需手动集成cloudwego工具链：kitex须在gopath/bin且path生效；go.work项目需右键load project with go workfile；.env加载冲突时应禁用envfile插件改用program arguments传参。
GoLand 本身不内置 CloudWeGo 工具链支持，必须手动集成 kitex、hertz、eino 等 CLI 工具，否则生成代码、调试服务、运行脚手架都会失败。
kitex 命令行工具必须出现在 GOPATH/bin 且被 GoLand 识别
GoLand 的 Kitex 插件（非官方）或自定义外部工具依赖系统 PATH 中可执行的 kitex。如果执行 kitex --version 在终端成功，但在 GoLand 的 Terminal 或 Run Configuration 中报 command not found: kitex，大概率是 GoLand 启动时未加载 shell 的 PATH（尤其是 macOS 的 zsh 配置未被 GUI 应用继承）。
- 验证方式：在 GoLand Terminal 中运行
echo $PATH，确认输出包含$GOPATH/bin（如/Users/xxx/go/bin） - 修复方法：macOS 下在
~/.zshenv（而非~/.zshrc）中添加export PATH="$GOPATH/bin:$PATH"；Linux/Windows 检查系统级环境变量是否生效 - 替代方案：在 GoLand 的
Settings → Tools → Terminal中设置 Shell path 为/bin/zsh -i（带交互模式），强制加载完整环境
GoLand 中配置 kitex 生成代码需绕过默认 GOPROXY 限制
kitex 生成器在解析 .thrift 或 .proto 时会动态拉取依赖模板（如 github.com/cloudwego/kitex/tool/internal/codegen），若本地 GOPROXY 设为 https://goproxy.cn，部分内部模板路径可能因重定向或缓存策略导致 failed to load template 错误。
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
- 临时解决：在生成命令前加环境变量
GOPROXY=direct go run -mod=mod ./cmd/kitex main.go - 推荐做法：将 kitex 安装为本地二进制（
go install github.com/cloudwego/kitex/tool/cmd/kitex@latest），再通过 GoLand 的External Tools配置调用，参数设为-module your-module-name -service your_service_name $FilePath$ - 注意：
$FilePath$必须指向 IDL 文件（如api/user.thrift），不能是目录，否则 kitex 会静默跳过
Hertz 和 Eino 项目无法被 GoLand 正确识别 module
CloudWeGo 的 hertz 和 eino 脚手架生成的项目默认使用 go.work 多模块工作区，而 GoLand 2024.2 及更早版本对 go.work 的索引支持不稳定——表现为无法跳转到 hertz.NewServer() 定义、eino.Run() 报 unresolved reference、测试文件无法识别 testutil 包。
- 检查点：打开项目根目录，确认存在
go.work文件且内容包含use ( ./app ./idl ./handler )类似结构 - 强制刷新：在 GoLand 中右键点击
go.work→Load project with Go Workfile（不是 “Reload project”） - 兼容性兜底：若仍无效，临时删掉
go.work，在各子模块目录下分别执行go mod init并用 GoLand 以“Open as Project”方式单独打开，再通过File → Project Structure → Modules手动聚合
EnvFile 插件与 Kitex/Hertz 的 .env 加载行为冲突
CloudWeGo 生态中，kitex 启动时默认读取 .env 注入服务名、监听地址等变量，而 GoLand 的 EnvFile 插件也会自动加载同名文件到 Run Configuration 环境中。两者叠加可能导致重复注入、类型转换失败（如 KITEX_PORT="8888" 被当成字符串而非 int）或覆盖预期值。
- 现象：
kitex server启动后监听:0（端口为 0），或日志中出现invalid port: strconv.Atoi: parsing "": invalid syntax - 解法：在 GoLand 的 Run Configuration → Environment variables 中清空所有自动注入项，改用
Program arguments传参，例如--addr=:8888 --service-name=user-svc - 关键提醒：
EnvFile插件只影响 IDE 运行时环境，不影响go run终端执行结果——所以务必区分“IDE 内 Run”和“Terminal 中手动 run”的行为差异
真正卡住团队协作的，往往不是 kitex 命令会不会用，而是不同成员的 GoLand 环境里，go.work 加载状态、GOPATH/bin 是否在 PATH、甚至 shell 初始化文件的加载顺序都不一致。建议把 .goland.sh 启动脚本和 go.work 校验逻辑写进 CI 的 pre-commit hook，比文档里写十遍“请检查环境”更可靠。
