前阵子接手一个园区运营大屏项目，从技术选型到真正上线折腾了小两个月，过程中踩了不少坑，也积攒了很多经验。当时我就在想，如果把整套从零到一的搭建过程完整记录下来，应该能帮不少人少走弯路。于是就有了这个系列，《从零搭建数据可视化大屏》，这篇是开篇，先把整体规划、技术路线、系列内容和开发规范一次性定下来，后面每一篇都会按这个框架推进。
我一直觉得，数据可视化大屏这类项目，最大的门槛不在写图表代码，而在怎么把数据、接口、布局、动效、部署这条链路完整串起来。你单独问ECharts怎么画个折线图，网上教程一大把，但真正动手做一个复杂大屏时，还是会卡在分辨率适配、数据刷新、组件通信这些几乎没人讲透的地方。这个系列要解决的，正是这些问题。
先交代一下读者画像和前置要求，方便你对号入座：如果你会基础的 HTML、CSS、JavaScript，能看懂简单 SQL 查询，就可以跟着这个系列走完整个项目；如果你已经做过简单大屏，想了解更规范的数据接入方式和工程化组织方法，这个系列同样适用。整个系列会用一个贯穿始终的业务场景——园区运营监控大屏，从环境准备、工程初始化、图表开发，到后端数据接口、WebSocket 实时推送，最后到部署上线，每一步都可以直接照着做。
1. 为什么一个“大屏项目”值得做成系列
1.1 大屏展示是所有企业的“门面工程”
很多人以为大屏项目就是把几个图表拼在一起放到页面上，实际做下来你会发现，它几乎横跨了前端、后端、数据、设计和运维的所有环节。一个正经的监控大屏，背后要接数据库或第三方接口，要做数据清洗和聚合，要在前端实现流畅的图表渲染和动效，要考虑不同分辨率和浏览器兼容，还要保证不崩、不卡、不错位。企业里不管是用在展厅、汇报室还是监控中心，大屏都是最容易拿到台面上被审视的系统，做得漂不漂亮、稳不稳定，直接影响别人对整个技术团队能力的判断。
正因为如此，我不能只教你怎么画图表，而是要把一套能真实上线的大屏项目拆开揉碎。在这个系列里，你会看到一个项目从空目录开始，怎么一步步长成包含前端界面、后端服务、数据配 置、自动部署的完整代码库。这个过程本身就是一条非常典型的前端团队项目链路，掌握了它，以后不管做什么类型的数据产品，方法都是通用的。
1.2 这类项目到底卡住了哪些人
我见过太多人卡在中间状态。刚开始接触大屏的初级前端，会写代码但不知道怎么把项目从零搭起来；后端开发想快速搞定可视化展示，却发现图表交互和视觉细节比想象中麻烦；产品、测试或运维同学被安排来做大屏，搜索了一堆教程，却被各种碎片化内容搞得越来越乱。这些人的共性问题不是不努力，而是缺一条完整的主线。
网上关于 ECharts 单图表的教程非常多，但一旦涉及“图表和数据接口怎么对接”“多个图表组件如何共享一份数据”“部署后字体为什么变模糊”，能讲清楚的文章就很少了。这个系列最大的价值，就是帮你把这些碎片拼成一条完整的主线。跟着走一遍，相当于在一个虚拟项目里提前踩完所有的坑。
1.3 一个可复用的大屏项目比一百个片段有用
我做过的前几个大屏项目，基本都是一次性代码，赶完上线就再也没维护过，等到下一个项目来了又要重写。后来我发现，真正好用的不是某个图表写得多炫，而是能不能沉淀出一套可复用的工程模板 —— 目录结构清晰、图表组件化、接口统一封装、部署脚本一键执行。这套东西一旦搭好，换一个业务场景，改改数据和布局就能快速产出新的大屏。
这个系列最终交付的，就是这样一个基础工程。你会在后面几篇里看到一套合理的目录结构、一份统一的数据接口约定、一套图表基础组件和页面框架。文章里提到的所有代码都会按实际项目结构呈现，你可以直接把整个仓库克隆下来改造，也可以参考它的组织方式重写自己的版本。
2. 技术路线选型：我为什么这么搭
2.1 可视化库：ECharts 为主，AntV 为辅
大屏项目里最常见的两个可视化库是 ECharts 和 AntV 系列。我之前两个都实际用过，最终这个系列选择了 ECharts 作为主力，原因很直接：它在国内社区里的案例和文档是最丰富的，遇到问题搜一下基本都能解决；graphic 和 dataZoom 等高级能力支持得很完善；还有一点很关键，它对 Canvas 渲染做了大量优化，在数据量大、图形元素多的时候依然能保持流畅。
这不代表 AntV 没有优势。G2Plot 在统计图表的规范性和视觉细节上做得更细腻，如果你的团队对图表的统计口径和视觉一致性要求特别高，也可以考虑。我在项目中是这么处理的：通用业务图表通通用 ECharts，个别对统计严谨性要求高的图表——比如某些趋势对比图，会用 G2Plot 单独补充。你在自己项目里也可以按这个思路灵活搭配，不要把技术栈锁得太死。
2.2 后端接口层：Node.js + Express，省心第一
真要做能用的项目，前端页面不可能一直连 mock 数据，总要有一个服务端提供真实数据。后端框架我选了 Node.js + Express，核心原因是：前后端都用 JavaScript，类型和数据结构不用来回切换；JSON 数据天然契合，处理起来非常顺手；前端开发者不需要额外学一门语言就能看懂整个项目的后端部分。如果你是纯前端背景，用这套组合几乎是无缝衔接。
当然，如果你的团队后端是 Python 技术栈，完全可以用 FastAPI 替代。实际项目里用哪种，取决于团队现有环境和部署条件。下表是我在选型时做的一组对比，供你参考：
| 技术栈 | 上手成本 | 适合场景 | 数据接口处理 | 与前端配合 |
|---|---|---|---|---|
| Node.js + Express | 低（前后端同语言） | 中小屏项目、前端主导 | 快，天然 JSON | 好 |
| Python + FastAPI | 中 | 已具备 Python 服务、算法集成 | 较好，类型更严格 | 一般 |
| Java + Spring Boot | 中高 | 大厂现成中间件生态 | 强，适合复杂业务 | 一般，联调成本略高 |
2.3 数据存储与实时更新方案：从静态 JSON 到 WebSocket
项目里的数据怎么来，是很多新手最容易忽略的问题。我建议的演进路径是：前期用静态 JSON 文件把界面和图表全部做出来，这一步只关注前端视觉和交互；确定页面没问题后，再接入后端接口把 JSON 数据替换成数据库或者第三方接口返回的数据；最后如果业务需要实时变化（比如能耗监控、告警消息），再用 WebSocket 推送实时数据。
数据库我选了最常用的 MySQL，你也可以用 PostgreSQL。这里要特别说明一个常见误解：不是所有数据都必须实时连接数据库。真实的运营大屏里，很多指标更新频率没那么高，半小时甚至一天更新一次完全够用，这时用一个定时任务去刷新缓存就足够了。盲目把所有数据都做成实时推送，只会增加开发和部署成本。
2.4 为什么不用低代码大屏平台
肯定有人会说，市面上一堆低代码大屏工具，拖拽一下就能生成，为什么要自己写代码？我确实用过这类平台，它们在快速原型和一次性展示场景下很有优势，但遇到下面几种情况就很难受：非标准布局定制麻烦，图表交互深度受限，私有化部署成本高，数据安全难以控制。尤其是公司要求数据不能出内网的时候，大部分在线低代码平台根本没法落地。
自己搭一套工程，前期确实多一些工作量，但长期看可控性是完全不一样的。你能完全掌控页面的每一像素，能对接任意数据源，能自由扩展业务能力，部署到哪里都不受限制。这个系列选择了自己搭建，就是要带你掌握这种可控性。等你有经验后，再结合低代码平台提升效率，会是更好的组合。
3. 系列整体规划：用一套真实项目把内容串起来
3.1 一个贯穿始终的业务场景：园区运营监控大屏
为了不让技术讲解悬在半空，这个系列会统一围绕一个业务场景展开：某科技园区的运营监控大屏。屏幕内容包含园区实时能耗曲线、设备运行状态分布、各楼栋人流量热力图、当日告警信息列表，以及几个核心经营指标卡片。这些模块基本覆盖了大屏项目常见的图表类型和交互能力。
选择这个场景有几个好处：数据含义直观，不需要业务背景也能理解每个图表在表达什么；图表类型丰富，折线图、柱状图、饼图、热力图、滚动列表都有覆盖；实时数据推送和告警联动的需求也很自然，能顺理成章地讲清楚 WebSocket 的落地写法。每篇代码都会围绕这个场景展开，场景稳定了，你就能把注意力完全放在技术实现上。
3.2 八篇内容，篇篇都有明确交付物
这个系列规划了八篇内容，先后顺序和依赖关系是仔细考虑过的。你不需要在开篇就看完所有代码，但强烈建议按顺序跟进，因为后一篇基本都是在前一篇代码基础上修改的。
| 篇章 | 主题 | 核心交付物 |
|---|---|---|
| 第一篇 | 开篇与整体规划（本篇） | 技术选型、系列规划、目录结构、开发规范 |
| 第二篇 | 环境准备与前端工程初始化 | 可运行的 Vue3 + Vite 空项目骨架 |
| 第三篇 | 大屏布局与视觉设计 | 16:9 自适应页面、栅格布局、基础组件封装 |
| 第四篇 | ECharts 核心图表开发 | 折线图、柱状图、饼图、热力图完整代码 |
| 第五篇 | 数据接入与接口联调 | Express 接口服务、MySQL 数据库、统一响应格式 |
| 第六篇 | 动态数据与 WebSocket 实时刷新 | 实时数据推送、前端自动更新、断线重连 |
| 第七篇 | 性能优化与部署上线 | 构建优化、Nginx 部署、常见踩坑清单 |
| 第八篇 | 项目复盘与扩展思路 | 组件复用、主题切换、多项目快速交付方案 |
3.3 时间预估与学习建议
按照我自己的实测，每天能抽出两小时的话，三到四周可以完整走完这个系列并产出自己的工作。前几篇进度会快一些，到了数据接入和 WebSocket 部分容易遇到环境问题，多预留时间调试。
我给新手的建议很简单：每一篇都要动手敲，不要只是看；遇到报错先自己读错误信息，尝试定位是语法问题、路径问题还是接口问题，实在解决不了再去搜索或留言；觉得代码没问题但是效果不对时，先对比自己的代码和示例代码的差异。这个过程虽然慢，但训练的是独立排查问题的能力，这是只看教程学不到的。
4. 开工前的准备工作：目录结构、环境与开发规范
4.1 本地开发环境
按这个系列搭建项目前，先把基础环境配好。我使用的是 Node.js 18 及以上版本，因为 Vite 5 和较新的生态工具都明确要求这个版本；包管理器用 pnpm，安装速度快、磁盘占用小，对于多依赖的前端项目体验提升明显；代码编辑器推荐 VS Code，下面几个插件强烈建议安装：ESLint、Prettier、Vue Language Features（Volar）、TypeScript Vue Plugin。
版本这块经常有人踩坑，我用表格列一下当前实测可用的组合，你直接用这套可以规避大部分版本兼容问题：
| 工具 | 推荐版本 | 备注 |
|---|---|---|
| Node.js | 18.20 或更高 | 低版本会造成 Vite 启动失败 |
| pnpm | 9.x | npm 也可，但推荐 pnpm |
| Vue | 3.4+ | 组合式 API 写法 |
| Vite | 5.x | 构建快，配置简单 |
| ECharts | 5.5+ | 注意别用 4.x 旧版 |
4.2 推荐的前端工程目录结构
一个清晰合理的目录结构，是大屏项目长期可维护的基石。下面这个结构是我在多个项目里反复调整后沉淀下来的，后面几篇都会按照这个约定继续组织代码：
dashboard/ ├── public/ # 静态资源，直接复制不参与构建 ├── src/ │ ├── api/ # 所有接口请求封装 │ ├── assets/ # 样式、图片等资源 │ ├── components/ │ │ ├── common/ # 通用组件（标题、边框、滚动列表） │ │ └── charts/ # 图表封装组件 │ ├── composables/ # 复用的逻辑函数 │ ├── config/ # 页面配置、主题配置 │ ├── router/ # 路由 │ ├── store/ # 全局状态 │ ├── utils/ # 工具函数 │ ├── views/ # 页面级组件 │ ├── App.vue │ └── main.ts ├── .env.development # 开发环境变量 ├── .env.production # 生产环境变量 ├── index.html ├── package.json └── vite.config.ts这里有一个我自己很看重的原则：图表组件尽量单独拆出来，不要直接在页面里堆 ECharts 初始化逻辑。你后面会看到，每类图表都被封装成独立的 Vue 组件，通过 props 接收数据和配置项，页面对图表只有声明式的使用关系。这样改一个图表不影响页面，换数据源也只需修改对应组件，整个项目的维护成本会直线下降。
4.3 Git 分支管理与提交规范
只要是正经项目，就一定绕不开多人协作和版本管理。这个系列虽然是单人开发流程，我依然建议从头就按照规范来，免得习惯养坏了后面参与团队项目时吃亏。分支模型用最经典的main/develop/feature/*模式：main分支只放可以发布的稳定版本；日常开发在develop上进行；每开发一个新功能或新页面，从develop拉出feature/xxx分支，完成后再合并回来。
提交信息我建议直接用 Conventional Commits 规范，看起来很简单，但坚持下来对后期追溯特别有帮助。比如：
git commit -m "feat(charts): 新增能耗趋势折线图组件" git commit -m "fix(api): 修复告警列表接口超时未重试的问题" git commit -m "refactor(utils): 抽取通用格式化函数"格式上的规范看似在增加工作量，实际上是在为项目的未来铺路。我见过太多项目上线三个月后，没人敢动某个模块，就是因为代码没有规范约束，改一处崩一处。从开篇开始就按规范走，后面每一篇示例代码才能有稳定的基础。
5. 大屏项目最容易踩的坑与我的避坑心得
5.1 图表组件化不够，导致一屏崩溃
第一个想重点提醒的坑，就是图表组件化。我早期做项目时图省事，直接在页面组件里复制粘贴 ECharts 初始化代码，结果页面里五六个图表互相干扰，窗口缩放后图表变形，组件销毁后定时器没有清理，内存一直涨。排查问题时，代码搅在一起非常痛苦。
解决办法就是先把 ECharts 初始化、销毁、尺寸自适应这些逻辑统一封装成基础组件，页面里只传数据和配置。后来我把这套组件抽到公司内部公共库里，新项目做图表开发，时间压缩了一大半。这个系列的第四篇就会完整实现这套封装，用过你就知道有多舒服。
5.2 分辨率适配只做了缩放，忽略字体和间距
大屏开发里最经典的坑就是分辨率适配。很多人第一反应是写 CSS transform 缩放到全屏，页面文字确实跟着缩放了，但字体清晰度、响应式布局和滚动交互很容易出问题。正确做法是：以 1920x1080 为基准设计稿，用 rem 方案动态计算根字体大小，让图表容器宽度和高度按比例自适应，同时保证在 2K、4K 屏上也清晰。
这里有个细节容易被忽略：ECharts 的字体大小和间距也是基于像素的，如果只用 CSS 缩放整体页面，图表内部标注会跟着模糊。正确的思路是监听页面尺寸变化，把当前缩放比例传进图表配置里，让 ECharts 按比例重新渲染。具体实现我会在第三篇布局篇里详细讲解，这里先标记为重点。
5.3 实时刷新直接 setInterval，没有防抖与重连
到了动态数据环节，最容易翻车的写法就是粗暴地在每个图表组件里setInterval请求数据。表面上看起来每个图表都在自动刷新，实际上请求频率混乱不说，还很容易重复请求，后端接口直接被压垮。正确思路是：在页面层级统一管理数据轮询，拿到新数据后用事件总线或状态管理分发到各个图表组件；同时添加请求失败重试和前端兜底机制。
更进阶一点的方案就是 WebSocket。如果你对“为什么 WebSocket 比轮询更好”还不太清楚，可以记住一句话：轮询是前端每隔一段时间去问服务端“有数据吗”，WebSocket 是服务端觉得有变化了主动推给前端“数据变了”。这个系列第六篇会把 WebSocket 的完整接入、断线自动重连、心跳保活机制全部讲透。
5.4 给新手的几条实用建议，都是花钱买来的教训
最后聊几条我用真金白银换来的经验。第一条，先用假数据把整个页面做完，再接真实接口。很多人一上来就想着连数据库，结果界面还没搭好，就卡在跨域、鉴权、字段对不上这些事上。先用静态 JSON 把视觉和交互做好，界面稳定后再替换成接口数据，效率翻倍。
第二条，先把所有图表实现出来，再去做动效和装饰。大屏最容易沉迷进去的就是各种飞线、呼吸灯、粒子效果，这些确实好看，但先把核心图表跑通更重要。项目时间紧张时，装饰完全可以砍掉，图表信息准确才是第一位的。
第三条，有条件的话找一台真实的落地大屏或电视去测一测。很多效果在电脑浏览器上很好，到了大屏上就出现颜色偏淡、字体模糊、触摸不灵敏等奇怪问题。提前找目标设备联调，能省去上线前最后一轮返工的成本。
做数据可视化大屏，说到底就是把数据和视觉用工程化的方式稳定地连接起来。技术上没什么高深的东西，但每一环都有它独有的细节，这也是我记录这个系列的原因。后面每一篇，我都会用同样的节奏，把原理、代码、踩坑和可复用的方案一并写清楚，跟着做完，你一定会有自己的可交付作品。
