go version正常但go run报command not found，说明GOROOT/bin已加入PATH，但GOPATH/bin（如$HOME/go/bin）缺失，而go install生成的工具依赖该路径；需补全export PATH=$PATH:$HOME/go/bin并source配置文件。
go version 显示版本但 go run 报 command not found
说明 go 命令在 shell 中可执行，但 go run 找不到 Go 工具链里的子命令——本质是 GOPATH 或 GOROOT 未正确注入到 PATH。常见于 macOS/Linux 下用二进制包手动解压安装后只加了 GOROOT/bin，漏掉 $GOPATH/bin（尤其当你用 go install 安装第三方工具时）。
检查方法：
echo $PATH | grep -E "(go|Go)"看是否同时包含
/usr/local/go/bin（或你自定义的 GOROOT）和 $HOME/go/bin（默认 GOPATH）。若缺失后者，补上：export PATH=$PATH:$HOME/go/bin（写入
~/.zshrc 或 ~/.bashrc 后 source）。
注意：Go 1.16+ 默认启用 GO111MODULE=on，不再依赖 GOPATH 构建项目，但 go install 生成的可执行文件仍默认落在 $GOPATH/bin，所以该目录必须在 PATH 中才能直接调用。
vscode 中调试不触发断点，或显示 “no debug adapter”
这是 VS Code 的 Go 扩展没配好，不是 Go 环境本身问题。Go 1.24 起官方推荐使用 dlv-dap（Delve 的 DAP 实现），而非旧版 dlv。
立即学习“go语言免费学习笔记（深入）”；
操作步骤：
- 确保已安装 Delve：
go install github.com/go-delve/delve/cmd/dlv@latest - VS Code 设置中搜索
go.delvePath，将其值设为$HOME/go/bin/dlv（macOS/Linux）或%USERPROFILE%\go\bin\dlv.exe（Windows） - 在项目根目录下运行
go mod init example.com/hello（哪怕只是测试文件），否则 VS Code 不识别为 Go 项目，调试器不加载 - 调试配置
.vscode/launch.json中的type必须是go，且mode为auto或test（非exec）
常见坑：用 go run main.go 运行时断点有效，但用 go test 调试时没反应——因为没在 launch.json 里把 mode 设成 test，或测试文件名不符合 *_test.go 规范。
go test -v 输出 “no test files” 却明明有 *_test.go
Go 测试文件必须同时满足两个条件才被识别：文件名以 _test.go 结尾，且 内部至少有一个函数签名形如 func TestXxx(t *testing.T)（首字母大写的 Test 前缀 + 大写字母开头的后缀）。
典型错误：
-
func testAdd(t *testing.T)→ 小写test，不被识别 -
func Test_add(t *testing.T)→ 下划线在大写前，Go 规定后缀必须全为字母，不能含下划线 - 文件放在
internal/目录下，但当前go test命令没指定该子目录（go test ./internal/...才行） - 文件里只有
BenchmarkXxx或ExampleXxx，没有TestXxx函数
快速验证：在终端运行 go list -f '{{.TestGoFiles}}' .，它会列出当前目录下所有被识别为测试文件的 *_test.go；若为空，说明命名或函数签名有误。
go build 生成的二进制无法运行：”cannot execute binary file”
这几乎一定是平台不匹配导致的——你在 macOS 上用 GOOS=linux go build 交叉编译出 Linux 二进制，却双击或 ./app 在 macOS 上执行。Go 编译默认绑定宿主平台，跨平台需显式指定 GOOS 和 GOARCH，但生成的文件只能在目标平台运行。
检查方式：file app（Linux/macOS）或 Get-Command app | % Extension（PowerShell）看文件类型。若显示 ELF 64-bit LSB executable，那就是 Linux 二进制，不能在 macOS 运行。
实用建议：
- 日常开发就用默认编译：
go build，不加任何GOOS，保证本地可跑 - CI/CD 中需要多平台产物时，才用
GOOS=windows GOARCH=amd64 go build等组合，并明确区分输出路径（如-o dist/app-linux） - 容器部署时，Dockerfile 中的
FROM golang:alpine是构建环境，最终COPY进去的是宿主平台编译的二进制（比如你本地 macOS 编译的），只要基础镜像支持该二进制格式（Alpine 支持 Linux amd64），就能跑
最容易被忽略的一点：M1/M2 Mac 上编译的二进制默认是 arm64，但某些老工具链或 CI 环境仍设为 amd64，导致本地能跑、CI 报错。用 go env GOARCH 确认当前架构，必要时强制 GOARCH=arm64 go build。
