连 InfluxDB 1.x 用 influxdb/influxdb-php（用户名密码认证），2.x/Cloud 必须用 influxdata/influxdb-client-php（token+org+bucket 认证），版本错配会导致 401 或 404 错误。
PHP 连 InfluxDB 用哪个客户端库
InfluxDB 官方不维护 PHP SDK，社区主流方案是用 influxdb/influxdb-php（原 php-influxdb），但注意：它只支持 InfluxDB 1.x 的 HTTP API；InfluxDB 2.x 或 Cloud 需用 influxdata/influxdb-client-php（官方维护，基于 v2 API + token 认证）。
别混淆版本——连错库会直接报 401 Unauthorized 或 404 Not Found，尤其当服务端是 2.7+ 或 InfluxDB Cloud 时，influxdb/influxdb-php 根本不通。
- 1.x 环境（如自建 1.8）：用
influxdb/influxdb-php，配置username/password即可 - 2.x / Cloud：必须用
influxdata/influxdb-client-php，依赖token和org参数，database概念已替换为bucket - Composer 安装命令不能混：
composer require influxdb/influxdb-phpvscomposer require influxdata/influxdb-client-php
连 InfluxDB 2.x 报 “Unauthorized” 怎么调
这是最常见卡点——不是密码错，而是没配对认证三要素：url、token、org。InfluxDB 2.x 废除了 user/pass，改用 token 绑定 org 和 bucket 权限。
检查这三点：
立即学习“PHP免费学习笔记（深入）”；
-
token必须是完整字符串（含长串字母数字和下划线），从 UI 的 Load Data → Tokens 复制，别手输漏字符 -
org是组织名（不是用户名），默认是安装时填的邮箱，但可能被改过；可在 UI 右上角头像 → Organizations 确认 -
bucket名要全匹配（区分大小写），且该 token 必须有该 bucket 的读/写权限（Token 权限页里勾选）
示例初始化代码（v2 client）：
$client = new InfluxDB2\Client([
"url" => "https://us-west-2-1.aws.cloud2.influxdata.com",
"token" => "xxx_xxx_xxx==",
"bucket" => "my-bucket",
"org" => "my-org@example.com"
]);
PHP 写入时序数据失败但没报错？
常见于批量写入（writeRecords()）时字段类型不一致或时间戳格式错。InfluxDB 对 line protocol 极敏感，一个点格式错，整批丢弃且默认静默失败（除非显式 catch 异常）。
- 时间戳必须是纳秒级整数（非字符串），或留空由服务端打时间；若传字符串，格式只能是 RFC3339（如
"2024-05-20T10:30:00Z"），Y-m-d H:i:s会直接拒收 - 字段值不能是
null，空值要用0或""显式替代；布尔值必须小写true/false，大写或字符串"true"会解析失败 - 写入前建议先用
print_r($lineProtocol)打印原始行协议字符串，对照文档检查格式：例如cpu,host=server01,region=us-west usage_idle=99.64 1695284520000000000
查询返回空数组却没报错？
多半是 Flux 查询语句语法错，或者时间范围没覆盖数据。InfluxDB 2.x 查询不用 SQL，用 Flux 脚本，错误不会抛异常，而是返回空结果集。
- 确认时间范围：Flux 默认只查最近 1h，用
range(start: -12h)显式扩宽，或用绝对时间range(start: 2024-05-20T00:00:00Z, stop: 2024-05-20T23:59:59Z) - bucket 名必须和写入时一致，且带引号：
from(bucket: "my-bucket")，不加引号会报错 - 字段名、tag 名区分大小写，
filter(fn: (r) => r._field == "temperature")中_field是系统字段，不能写成field - 调试时先在 InfluxDB UI 的 Script Editor 里跑通 Flux，再复制到 PHP
真正麻烦的是 Flux 语法和 PHP 数据结构映射——比如它返回的每行是 map 结构，_value 是数值，_time 是 RFC3339 字符串，得自己转换时间戳，这点容易被忽略。
