QueryAPI.Query() 返回空 slice 且 err == nil 的主因是 Flux 脚本错误，最常见的是遗漏末尾的 |> yield()；其次为时间范围不匹配、特殊字符字段名未加引号、未正确遍历 Tables()/Records() 等。
QueryAPI.Query() 返回空 slice 且 err == nil，基本不是连接或权限问题，而是 Flux 脚本本身没写对。
Flux 查询必须显式加 |> yield()
这是最常被忽略的硬性语法要求。InfluxDB 2.x+ 的 Flux 执行模型默认不输出任何结果——哪怕查询逻辑完全正确、数据真实存在，漏掉 |> yield() 就等于“执行了但什么也不返回”。
-
yield()必须出现在管道末尾，例如：`from(bucket:"my-bucket")|>range(start:-1h)|>filter(fn:(r)=>r._measurement=="cpu")|>yield()` - 如果用了多个
|> filter或|> aggregateWindow，|> yield()仍只需一个，放在最后 - 不加 yield，
QueryAPI.Query()会安静地返回空[]，err也是nil，毫无提示
时间范围 range() 写错导致查不到数据
range(start: -1h) 只查最近 1 小时，而你的数据可能在昨天、上周，甚至更早。调试时最容易误判为“没写进去”，其实是查偏了。
- 先用 InfluxDB UI 的 Data Explorer 直接跑同一段 Flux，确认数据是否存在、时间是否匹配
- 临时把
range()改成宽泛范围，比如range(start: -7d)或具体时间戳：range(start: 2026-10-02T00:00:00Z, stop: 2026-10-03T00:00:00Z) - 注意：InfluxDB 默认使用 UTC 时间，Go 中传入的
time.Time若未显式设为 UTC，可能导致时区偏差
字段名含特殊字符（如 -）必须用双引号包裹
Flux 解析器对标识符有严格要求。像 cpu-usage 这类带连字符的字段名，不加引号会直接解析失败，但错误不暴露在 Go 层——Query() 仍返回空，err 为 nil。
立即学习“go语言免费学习笔记（深入）”；
- 错误写法：
filter(fn: (r) => r.cpu-usage > 80)→ 解析失败，静默无结果 - 正确写法：
filter(fn: (r) => r["cpu-usage"] > 80)或filter(fn: (r) => r."cpu-usage" > 80) - 标签名同理，
r.host-name必须写成r["host-name"] - 建议整个 Flux 字符串用反引号
`包裹，避免 Go 字符串转义干扰，例如：`from(bucket:"my-bucket")|>filter(fn:(r)=>r["cpu-usage"]>80)`
结果解析必须遍历 Tables() 再取 Records()
Flux 返回的是多表结构（比如按 tag 分组后生成多个 table），不是扁平 record 列表。跳过 table 层直接调 result.Records() 会 panic，因为该方法根本不存在。
- 正确路径：
for _, table := range result.Tables() { for _, record := range table.Records() { ... } } -
record.ValueByKey("_value")可能返回nil，不判空直接.Value().(float64)断言会 panic - 时间统一用
record.Time()，数值字段用record.ValueByKey("xxx")，别混用已废弃的record.Field() - 字段名若来自动态 tag（比如
r.tag_name），别硬编码 key，先用record.Values()看实际键名和类型
真正卡住人的地方往往不在语法本身，而在 Flux 的“静默失败”机制：不报错、不 panic、不提示，只悄悄返回空。每次 Query 前，先在 UI 里跑通 Flux，再复制到 Go 里，能避开 90% 的排查时间。
