ThinkPHP后台图表统计核心卡点是数据组织方式、类型一致性及前后端字段契约；90%空白或报错源于field()未显式声明别名、sum()/avg()返回字符串、JSON响应含干扰输出。
ThinkPHP 后台图表统计不是“把数据塞进 ECharts 就完事”，核心卡点在数据组织方式、类型一致性、以及前后端字段契约——90% 的图表空白或报错，都出在这三处。
聚合查询必须用 Db::name() + field() 显式声明字段
GROUP BY 统计不能只靠 group('status')，否则返回的数组字段名是数据库原始列名，和 ECharts 要求的 xAxis/series 对不上。TP 不会自动帮你映射别名。
-
field()必须写出所有要返回的字段，包括分组字段和聚合结果，且别名要用as：比如field('status as name, count(*) as value') - 如果字段含中文或特殊字符（如
category_name），得加反引号：field('`category_name` as name, sum(amount) as value') - 别在
group()后接count()——那只会返回分组总数（比如 5 个 status），不是每个 status 的记录数 - TP6 中若用模型调用，确认没开启
autoWriteTimestamp，否则created_at类字段可能被自动注入干扰select()结果
sum() / avg() 返回值类型不等于字段类型
数据库字段是 VARCHAR 存金额？sum() 可能返回字符串甚至科学计数法，ECharts 渲染折线图时直接报 NaN。这不是 PHP 类型转换问题，是字段设计缺陷。
- 先查字段类型：
SHOW COLUMNS FROM `order` LIKE 'amount'，确保是DECIMAL或INT - TP6 中
sum()默认返回float，但如果底层 MySQL 返回的是字符串（比如某些配置下），就得手动强转：(float) Db::name('order')->sum('amount') - 聚合结果用于饼图时，
value字段必须是数字；若从 Redis 拉取限流数据（如Cache::get('api:rate:...')），它永远是 string，必须在控制器里写成'count' => (int) $cached
接口返回 JSON 前必须清空所有干扰输出
只要控制器方法里出现一次 echo、var_dump、print_r，或者模板里多一个空格，前端 JSON.parse() 就会失败，ECharts 显示空白但控制台无报错。
立即学习“PHP免费学习笔记（深入）”；
- 务必用
return json($data)（TP6）或return $this->success('', '', $data)（TP5.1），不要echo json_encode() + exit - 关闭调试模式：
app_debug = false，否则 ThinkPHP 会在响应末尾追加 HTML 调试面板，破坏 JSON 结构 - 检查路由是否带了多余中间件（比如日志记录中间件写了
echo），这类问题只能靠curl -v直接看原始响应体 - 返回数组键名必须和前端 JS 完全一致：
['xAxis' => [...], 'series' => [...]]，写成categories或dataList就拿不到数据
ECharts 初始化前 DOM 必须就绪且容器有宽高
后端数据再准，前端初始化时机错了，图表照样不显示。“Cannot set property ‘option’ of null” 是典型症状，不是后端问题。
-
<div id="chart"></div>必须在 HTML 中真实存在，不能靠 JS 动态插入后再 init - JS 初始化代码不能放在
<head>里，除非加defer，或包裹在document.addEventListener('DOMContentLoaded', ...) - 容器必须有明确宽高：
style="width: 600px; height: 400px;"，仅设height: 100%不生效 - Vue/React 项目中，必须在
mounted或useEffect里初始化，不能在组件 render 阶段就调echarts.init()
真正难的不是写出第一个柱状图，而是当数据来自多个表 JOIN、含时间范围动态过滤、还要支持导出 Excel 时，聚合 SQL 和前端字段结构仍保持可读、可维护、不互相污染。
