Go环境配置失败主因是PATH未生效导致go version报错，或go mod init因路径推断错误失败；需手动验证which go或Get-Command go，正确配置GOROOT/bin到PATH，并强制启用GO111MODULE=on。
Go 环境装不起来，多半卡在 go version 报错或 go mod init 失败；监控告警跑不通，90% 是因为 /metrics 路径不可访问、Prometheus 抓不到目标，或 Grafana 数据源没连上 Prometheus API 地址。
确认 go 命令可用且模块模式开启
别信安装器勾选的“添加到 PATH”——它大概率没生效。终端里直接运行：go version，如果报 command not found，说明 PATH 没配对。
- macOS/Linux：检查
which go输出，若为空，把 Go 的bin目录（如/usr/local/go/bin）加进~/.zshrc或~/.bash_profile，再执行source ~/.zshrc - Windows：用 PowerShell 运行
Get-Command go，失败就去「系统属性 → 高级 → 环境变量」手动加C:\Program Files\Go\bin - 强制启用模块：运行
go env -w GO111MODULE=on，避免老项目残留的GO111MODULE=off干扰 - 新建项目前，确保不在
$GOPATH/src下（否则go mod init会按旧路径推导 module 名），直接在任意空目录下操作
暴露 /metrics 接口并注册自定义指标
只挂 promhttp.Handler() 只能拿到 Go 运行时指标（GC、goroutine 数等），业务指标必须显式定义并注册。漏掉 prometheus.MustRegister() 就等于没上报。
- 用
NewCounterVec或NewHistogramVec定义带标签的指标，比如按method和status统计请求量：httpRequestsTotal.WithLabelValues(r.Method, status).Inc() - 务必在
init()或main()开头调用prometheus.MustRegister(...)，否则指标不会出现在/metrics输出里 - 启动服务后，手动 curl 一下：
curl http://localhost:8080/metrics | head -20，确认能看到你定义的指标名（如http_requests_total），而不是只有go_开头的内置指标 - 别把 handler 放在路由中间件之后——如果用了 Gin/echo 等框架，
router.Handle("/metrics", promhttp.Handler())必须在所有中间件之前注册，否则可能被拦截
Prometheus 抓不到目标的常见原因
http://localhost:9090/targets 页面显示 DOWN，不是 Prometheus 本身坏了，而是网络、配置或服务端问题。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 检查 Go 服务监听地址：默认
http.ListenAndServe(":8080", nil)只监听localhost，如果 Prometheus 在另一台机器或 Docker 容器里，得改成http.ListenAndServe("0.0.0.0:8080", nil) - 确认
prometheus.yml中static_configs的targets地址可通：比如写成["host.docker.internal:8080"]（Mac/Win Docker Desktop），而非["localhost:8080"]（容器内 localhost ≠ 宿主机） - 抓取超时默认 10s，如果 Go 服务启动慢或首次响应慢，可在 job 配置里加
scrape_timeout: 30s - 检查防火墙或 SELinux：Linux 上
systemctl stop firewalld临时关掉试试；Docker 启动时加--network host或正确映射端口
Grafana 连不上 Prometheus 或查不到指标
数据源测试通过 ≠ 能查到指标。Grafana 默认用 http://localhost:9090，但这个地址是 Grafana 容器视角的 localhost，不是宿主机。
- Docker 部署时，Grafana 容器要和 Prometheus 容器在同一个 network，数据源地址填
http://prometheus:9090（前提是docker run --name prometheus） - 用
http://localhost:9090/api/v1/query?query=count%7Bjob%3D%22myapp%22%7D手动调 Prometheus API，确认能返回 JSON 结果，再排查 Grafana 配置 - Grafana 新建 dashboard 时，查询语句别直接写
http_requests_total——先点「+ Add query」，选对数据源，再在编辑框里输入，否则会提示 “No data” - 告警规则写在
rule_files里，但必须在 Prometheus 配置中启用evaluation_interval，且 Alertmanager 地址要配对（alerting.alertmanagers），否则规则只是摆设
最常被跳过的一步：改完 prometheus.yml 后没 reload（kill -SIGHUP $(pidof prometheus) 或用 /-/reload endpoint），导致新配置根本没生效。指标暴露、抓取、查询、告警，每环都依赖前一环的输出准确，少验一个环节，问题就卡在黑盒里。
