1. 项目定位与整体架构设计1.1 需求拆解先别急着写代码接到这个实时数据大屏需求时我一开始也犯了懒以为就是拿 ECharts 画几个图表摆上去。真正开始做才发现大屏和普通后台页面的开发逻辑完全不是一回事。需求方说得很简单把运营数据实时展示出来但落到前端得先搞清楚一堆前置问题大屏部署在什么分辨率下用的是拼接屏还是单块大屏数据多久更新一次实时性要求到秒级还是分钟级要不要告警声音允许断网容忍多少秒图表类型大概有哪些这些不先问明白后面每一行代码都可能白写。我当时梳理了一轮核心就三件事第一数据要从后端实时推过来不能靠前端轮询去拉因为订单量和在线设备这类数据对实时性要求高轮询几分钟一次的延迟扛不住第二大屏要适配在场馆里那台固定分辨率的主机但开发时我用的显示器只有 1920 分辨率必须有一套可靠的缩放方案第三图表多且更新频繁页面上同时挂十几个 ECharts 实例如何保证不卡顿、不掉帧、不内存泄漏。这三点决定了整个技术选型和架构设计的方向。1.2 技术栈选型为什么是 Vue 3 WebSocket 的组合选型这件事网上争论很多但实际做项目要的是匹配场景。我这次选的是 Vue 3 Vite TypeScript ECharts WebSocket 这套组合。React 当然也能做但在团队内 Vue 的熟练度更高而且 Vue 3 的组合式 API 在管理 WebSocket 连接状态、图表实例这类有生命周期的事物时非常顺手onUnmounted里做清理逻辑代码组织起来比 Options API 清晰不少。构建工具用 Vite 的原因很实在修改代码后的冷启动速度对调试体验影响太大了这个项目图表配置多要反复调样式Vite 的秒级热更新能让我把更多时间花在验证效果而不是等待编译上。ECharts 在可视化这块是一个比较稳的选择文档全、社区活跃、遇到坑能找到解法这是关键。实时通信方面我在 WebSocket 和 SSE 之间犹豫过但考虑到后端已经有现成的 WebSocket 服务而且后续可能要做双向通信比如从前端大屏发指令控制数据模拟就定了 WebSocket。选型有一个值得分享的心得不要为了技术新潮去选团队没把握的库。数字孪生站点的 3D 可视化、实时视频流接入这些听起来更炫但如果业务场景没有强需求优先级应该排在大屏稳定性之后。先把实时链路打通、把图表渲染稳了再考虑扩展。1.3 目录结构与数据流设计项目结构这块我参考了之前做几个中后台系统的经验但针对大屏场景做了调整src/ api/ websocket.ts // WebSocket 封装 adapter.ts // 后端数据格式到前端组件 props 的转换层 views/ dashboard/ components/ HeaderPanel.vue // 顶部指标卡 OrderChart.vue // 订单趋势图 MapPanel.vue // 地图分布 AlarmList.vue // 告警滚动列表 stores/ metrics.ts // Pinia 实时数据仓库 composables/ useWebSocket.ts useChart.ts // 图表实例管理 utils/ scale.ts // 大屏缩放 format.ts // 数字格式化这个结构里最关键的是adapter.ts这一层。后端推送的数据结构不可能完全符合前端展示需求比如后端给timestamp: 1719302400000图表需要[time, value]格式如果每个组件各自做转换改一个字段名就要全局搜替换。我在中间加了一层 adapter所有组件只消费自己定义的 props 结构后端格式变化只改动 adapter这是这个项目里我觉得做得最值的一个决定。数据流设计上后端 WebSocket 推送原始数据进入 Pinia store组件通过 computed 依赖 storestore 里做了数据的派发。这样设计的好处是图表切换页面再回来时数据不丢而且调试的时候可以单独看 store 里的数据流问题定位很快。2. WebSocket 实时链路的工程化落地2.1 前端连接管理与心跳机制WebSocket 封装成单例是必须的不然页面上多个组件各自 new WebSocket连接数直接起飞。我最开始写的就是两个组件各连一个浏览器 network 面板里全是 ws 连接后端同事直接过来找我聊人生了。连接管理这部分我封装了一个WebSocketManager核心逻辑是全局只有一个连接实例所有订阅者通过回调注册连接关闭时统一清理。心跳机制更是必不可少这个坑我踩得很深。国内网络环境下WebSocket 连接经 nginx 反代后默认 60 秒左右没有数据传输就会被服务端断掉表现就是页面右上角的数据突然不动了必须手动刷新才恢复。心跳方案我最终是这样实现的class WebSocketManager { constructor(url) { this.ws null this.heartbeatTimer null this.reconnectTimer null this.retryCount 0 this.listeners new Set() } connect() { this.ws new WebSocket(url) this.ws.onopen () { this.retryCount 0 this.startHeartbeat() } this.ws.onmessage (e) { const data JSON.parse(e.data) if (data.type pong) { this.heartbeatOk true return } this.listeners.forEach(fn fn(data)) } this.ws.onclose () { this.stopHeartbeat() this.scheduleReconnect() } } startHeartbeat() { this.heartbeatTimer setInterval(() { if (this.ws.readyState WebSocket.OPEN) { this.ws.send(JSON.stringify({ type: ping })) } }, 30000) } }心跳间隔我设置了 30 秒发送一次为什么不是 10 秒因为太频繁的 ping 对后端也是无效压力而且心跳包本身会重置代理服务器的超时计时器。30 秒对大多数 nginx 配置的 60 秒超时来说容错空间足够。2.2 断线重连与消息可靠性断线重连这块最简单的方案是onclose里直接setTimeout重连但问题很明显如果后端短暂不可用直接重连可能连续失败集中重连会对服务器造成压力。我用的是指数退避策略重连间隔从 1 秒开始每次失败翻倍直到上限 30 秒重连成功后重置计数。scheduleReconnect() { if (this.reconnectTimer) return const delay Math.min(1000 * Math.pow(2, this.retryCount), 30000) this.reconnectTimer setTimeout(() { this.retryCount this.connect() this.reconnectTimer null }, delay) }还有一个更隐蔽的问题断线期间数据没了。比如网络抖动 10 秒这 10 秒的实时数据就永久丢了。我这里的处理方案是断线重连成功后前端向后端发送一个{ type: resubscribe, lastSeq: lastMessageSeq }请求从断开序号开始补推。后端按序号增量推送。这就是为什么我在协议里维护了一个seq字段——前端收到的每一条业务消息都带自增序号前端记录最后一次收到的序号重连后带上它做补拉实现消息的不丢失。这个方案做完以后对消息乱序的容忍度也高了。以前我担心后端推送乱序会导致图表数据乱跳现在每条消息都带序号前端在 adapter 层做一次排序虽然增加了 10 行左右代码但可靠性提升了一个量级。2.3 后端配合要点Spring Boot 和 Django 的配置差异WebSocket 是前后端协作的活前端做得再好后端配置不对照样断。我这次接触的两个后端项目一个 Spring Boot一个 Django配置方式差异比较大。Spring Boot 这边关键配置在 yml 里server.websocket没有太多需要调的但要注意框架自带的握手拦截器超时时间。spring-boot-starter-websocket的注册代码如下Configuration EnableWebSocket public class WebSocketConfig implements WebSocketConfigurer { Override public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { registry.addHandler(myWebSocketHandler(), /ws/metrics) .setAllowedOrigins(*); } }Django 这边用的是 Channels配置稍微繁琐一点。asgi.py里要配置协议类型路由器settings.py里要配CHANNEL_LAYERS。最早我帮后端同事排查时发现消息一直推不过来一看CHANNEL_LAYERS用的默认 InMemory 层当了一阵 debug 用后来换成了 Redis 层才稳定。这是 Djangoo Channels 一个容易忽略的点生产环境不要用 InMemory 层进程重启消息就丢。前端与后端的连接地址开发环境会遇到跨域或者 ws 连接地址写死的问题。我的建议是WebSocket 地址不要硬编码放在.env文件里通过import.meta.env.VITE_WS_URL读取这样部署到不同环境时只需要改环境变量。2.4 实际踩过的坑nginx 超时、心跳竞态和消息乱序这一节专门讲讲我实际踩过的坑每一个都有代表性。第一个坑是 nginx 反向代理导致的连接假死。页面连接后能正常收数据但只要数据推送集中在某一个瞬间——比如整点报数——之后 2 分钟没有新消息连接就会被 nginx 断开。表面看是断线了但其实浏览器并不知道因为onclose事件在 TCP 半开状态下触发不了。表现就是图表停了但页面不报错。解决办法就是心跳机制用客户端主动 ping 保证连接的活跃性。如果你发现连接一直没有报错但数据停了优先确认心跳是否在工作。第二个坑是心跳回包和业务消息的竞态。我最开始把心跳响应也当成业务消息处理结果数据列表里频繁出现{ type: pong }的记录。后来在onmessage里做了一级判断心跳消息直接拦截不进监听器分发。这个看起来很小但如果不拦所有订阅回调都会收到一条无用 pong 消息图表数据处理逻辑就会多一层判断。第三个坑是消息乱序。后端多实例部署时同一个前端连接可能被路由到不同的后端实例而不同实例的时钟和队列处理顺序不同导致序号小的消息比序号大的消息后到。我在 adapter 层加了一个长度为 50 的滑动窗口窗口内做序号排序。如果消息序号相差超过 50就认为异常直接丢弃并记录日志。这个阈值怎么来的按每秒 10 条消息的推送频率、网络抖动不超过 5 秒来估算的。3. 大屏自适应布局与探针监测3.1 大屏适配为什么不能用常规响应式方案大屏和普通页面的最大区别是分辨率跨度极大。普通后台页面适配 1366 到 2560 就是极限但大屏项目里常见的部署环境是 1920x1080拼控大屏可能是 3840x1080 甚至更高。如果按 rem 做响应式字号和间距的换算会非常混乱图表里的像素值在 rem 方案下也会变得不可控。我的方案是用 transform: scale 做整体缩放。以设计稿 1920x1080 为基准页面内所有元素的尺寸都用固定像素写死外层套一个容器根据运行时的实际宽高计算缩放比例// utils/scale.ts export function setupScale() { const designWidth 1920 const designHeight 1080 const app document.getElementById(app) function resize() { const scaleX window.innerWidth / designWidth const scaleY window.innerHeight / designHeight const scale Math.min(scaleX, scaleY) app.style.transform scale(${scale}) app.style.transformOrigin left top } window.addEventListener(resize, resize) resize() }这里有个细节Math.min保证了等比缩放不会因为屏幕宽高比不同导致图表拉伸变形。用transformOrigin: left top确保缩放后左上角对齐配合外层容器居中视觉上不会有偏移。这样整个项目里所有的字体、间距、图表尺寸都非常直觉设计稿是多少就写多少不用做任何换算。3.2 与 rem 方案的取舍有同事跟我推荐 rem 方案说可以自动适配。我对比后还是坚持了 scale 方案原因有三个rem 方案需要把所有像素值改成 rem 单位改造量大而且第三方图表库内部用的是像素rem 改不进去。rem 在不同分辨率下是线性拉伸但大屏项目的核心是保证比例不失调等比缩放比线性拉伸更符合视觉设计。scale 方案保留了设计稿还原度 100%的确定性任何元素在哪个分辨率下都按设计稿的比例呈现调试时心智负担小。当然 scale 方案也有代价缩放后的页面在大屏上是以设计稿尺寸为中心等比放大的四周会有留白。这个在大屏场景里通常可以接受因为大屏内容是给远处观众看的留白可以被背景填充。如果你做的是拼接墙可能需要配合背景图案延展来遮住留白。3.3 探针监测大屏性能不能靠感觉大屏上线后最尴尬的情况是客户现场演示时卡成幻灯片。我这次提前做了一个很轻量的性能探针用PerformanceObserver和requestAnimationFrame持续监测帧率// utils/probe.ts export function createFpsProbe() { let frames 0 let lastTime performance.now() let fps 60 function loop() { frames const now performance.now() if (now - lastTime 1000) { fps frames frames 0 lastTime now if (fps 30) { console.warn([probe] FPS: ${fps}, attention) } } requestAnimationFrame(loop) } requestAnimationFrame(loop) return () fps }这个探针以每秒为窗口统计 rAF 回调次数如果连续几个窗口内 FPS 低于 30说明渲染链路出了问题。我在页面上还会把这个 FPS 数据实时显示在一个隐藏的小角标里按下快捷键CtrlShiftD才显示方便现场演示时快速确认性能状态。另一个有用的探针指标是 WebSocket 消息积压数。如果下游数据处理跟不上推送速度积压会持续增加。我在 store 里维护一个pendingCount字段每收到一条消息先入队、处理完成再出队如果pendingCount超过 50就告警提示数据处理耗时过长。这个探针帮我发现了一个隐藏 bug某次图表初始化过程中后端一次性补推了 200 条历史数据adapter 层处理不过来积压告警直接爆掉。后来我做了分批处理前 100 条合并渲染后续消息按批次 setTimeout 处理问题就解决了。4. 数据可视化与组件通信4.1 ECharts 在大屏场景下的配置细节ECharts 用了这么多年大屏场景下有几个配置项特别关键可以说直接影响性能。第一个是关闭动画。大屏数据每秒都在更新图表如果每个点都做动画过渡争抢主线程资源很严重。我建议在图表初始化时关闭或者大幅缩短动画时间option { animation: false, // 或 animationDuration: 50 // ... }对于实时更新的折线图动画反而会让数据感觉延迟关掉后每帧直接刷新视觉上更跟手。第二个是grid边距设置。大屏通常有边框线、背景纹理默认的 grid 边距会有 40-50px 的空白放到大屏上会显得图表和边框距离不协调。我一般设置grid: { left: 40, right: 30, top: 30, bottom: 30 }具体数值设计稿为准但这几个 20-40 的区间足够解决大部分问题。第三个是tooltip。大屏上的鼠标交互本来就因为远距离操作不方便tooltip 的trigger我建议从axis改成item或者只在指定组件开启。如果图表展示的数据太密集tooltip 默认跟随鼠标会导致频繁的 DOM 重绘关闭或延后触发能有效降低渲染压力。第四个是dataZoom的实时更新策略。大屏数据滚动展示时dataZoom的start和end需要联动新数据。如果每次更新都重设 dataZoom 的值会导致用户手动缩放状态被覆盖。我的处理方式是给 dataZoom 加id并用setOption的notMerge参数控制而不是整体 replace。4.2 前端传参规范与状态管理大屏项目的传参比普通页面更复杂因为参数来源有好多路URL query大屏跳转时带过来的、WebSocket 推送的消息、用户在大屏上手动筛选的条件。如果每个组件各自自己去解析 URL、自己去订阅消息代码会散落一地。我用的方案是URL 参数统一在路由守卫里解析一次塞进 Pinia store业务组件只从 store 读取。举个例子大屏有一个按车牌号筛选车辆的入口从别的页面跳过来时 URL 是这样/dashboard?plate京A12345路由守卫解析后放入 store 的filters.plate车牌输入组件和图表组件都只关注 store 的这个小状态这样 URL 变化、用户输入、后端推送的 filter 条件都走同一个数据流// stores/metrics.ts export const useMetricsStore defineStore(metrics, { state: () ({ filters: { plate: , dateRange: today }, metrics: {} }), actions: { updateFilters(filter) { this.filters { ...this.filters, ...filter } // 更新后通过 WebSocket 通知后端重新订阅 wsManager.send({ type: updateFilter, data: this.filters }) } } })车牌号这个场景我多提一句前端的输入框需要做车牌格式化国内车牌有新能源绿牌和普通蓝牌两种格式正则校验、去空格、字母大写归一化这些处理要在组件统一做不然传参到后端时格式不一致后端同学会很崩溃。4.3 实时数据更新策略全量替换还是增量追加WebSocket 推送过来的数据怎么更新到图表我一开始用最笨的方式每次收到消息就setOption全量替换。数据量小的时候没感觉等到监控点位多了每个点位每秒都推送页面就开始卡了。优化思路有两个方向。一是把全量替换改成增量更新。对于趋势图这种场景新数据是一条一条追加的我用setOption的series[0].data.push()配合notMerge: falseECharts 内部只 diff 变化的部分开销小很多。二是用splitLine和axisPointer的合理配置减少无关重绘。ECharts 在setOption时如果传入的 option 中某些字段没变化其实不会触发重绘但如果你每次都构造全新对象ECharts 内部的 zrender 需要重新遍历所有元素计算 diff。所以我用了一个小技巧在图表组件里缓存上一次的 option收到新数据后只在原对象基础上改data字段const baseOption { /* 大部分静态配置 */ } const chart echarts.init(el) chart.setOption(baseOption) function updateData(newData) { chart.setOption({ series: [{ data: newData }] }) }这样baseOption里的配置只参与第一次渲染之后每次更新只动数据明显降低了主线程的 CPU 占用。5. 附加能力大文件上传与 PDF 打印5.1 为什么大文件上传要用 Web Worker大屏项目本身不太涉及大文件上传但同平台的管理后台需要做报表导入一次要传几十 MB 的 CSV 文件我做了一个独立模块。为什么不直接input[typefile]然后FormData一把梭因为大文件在上传前要做切片、算 MD5、校验完整性这些 CPU 密集型操作这些操作放在主线程上用户拖一个文件进来页面直接卡住体验很糟糕。用 Web Worker 把切片的计算放到后台线程主线程只负责交互和进度条渲染。切片的逻辑可以这样理解把一个大文件按固定大小比如 2MB切成一堆小文件块逐块上传后端全部收齐后再合并。这样即使某个块上传失败也只要重传这一块不用整个文件再来一遍。// worker.js self.onmessage async (event) { const { file, chunkSize } event.data let offset 0 const totalChunks Math.ceil(file.size / chunkSize) while (offset file.size) { const blob file.slice(offset, offset chunkSize) // 计算当前块的 hash const hash await computeHash(blob) self.postMessage({ type: chunk-ready, offset, hash, blob }) offset chunkSize } }这里还需要提一个断点续传的思路。前端在 localStorage 里记录每个文件已上传的块索引刷新页面后重新上来时跳过已上传的块。实现上就是检查后端返回的已存在分片序号列表只传缺失的部分。对于动不动传几个 G 文件的场景这个机制几乎是刚需。5.2 页面截图与 PDF 打印的落地Web 页面打印 PDF 是另一个看起来简单、做起来坑多的需求。如果你只是要简单的打印window.print()加media print样式是最快的方案。我这次遇到的是要把大屏上的某个报表区域生成 PDF 并落地归档这就不能靠window.print()了因为打印预览会带上浏览器 UI而且排版不可控。我用了html2canvas加jsPDF的组合先用html2canvas把目标 DOM 节点渲染成 canvas再转成图片嵌入 PDF 中。async function exportPdf(element) { const canvas await html2canvas(element, { scale: 2, useCORS: true, backgroundColor: #fff }) const imgData canvas.toDataURL(image/jpeg, 0.95) const pdf new jsPDF(l, mm, a4) const margin 10 const pdfWidth pdf.internal.pageSize.getWidth() - margin * 2 const pdfHeight canvas.height * pdfWidth / canvas.width pdf.addImage(imgData, JPEG, margin, margin, pdfWidth, pdfHeight) pdf.save(${Date.now()}.pdf) }这里有一个重要参数scale: 2。如果不设置canvas 的默认分辨率不够生成的 PDF 放大后文字边缘会模糊。useCORS: true用于处理图表中的图片资源跨域问题大屏里如果有地图瓦片或者外部图片不加这个会生成失败。打印样式需要单独维护我在模块里同时提供了一份打印 CSS隐藏无关的导航、按钮、边框设定打印区域的绝对定位字号和留白按 A4 比例调整。打印类的 CSS 其实是一个容易被忽略的细节很多人做完打印预览才发现按钮跑到纸外面去了。5.3 与主项目的集成方式大文件上传和 PDF 打印这两个模块我都是做成独立封装不与主项目强耦合。方案的取舍很实际PDF 打印可能只在某个页面用到大文件上传更是平台后台功能如果都塞进大屏项目的首屏 JS 里体积会白白增加。所以两个模块都通过异步动态导入方式加载// 按需加载 async function handleExport() { const { exportPdf } await import(/utils/exportPdf) await exportPdf(document.getElementById(report-wrapper)) }这样主包体积不受影响用户用到时才去加载对应模块。还有一个集成细节PDF 打印模块里引用的html2canvas和jsPDF体积都不小打包时拆成独立 chunk避免和业务代码混在一起。这套按需加载的模式对于任何功能相对独立的模块都适用不只是这两个案例。6. 上线前性能体检与经验沉淀6.1 WebSocket 内存泄漏排查大屏项目跑一两天就会卡但重启浏览器又好了十有八九是内存泄漏。我这次排查内存泄漏时Chrome DevTools 的 Memory 面板起了大作用但核心问题和解决思路值得分享一下。最常见的泄漏来源是 WebSocket 消息回调没有正确解绑。组件onMounted里wsManager.listeners.add(this.handler)onUnmounted里如果没有 remove组件销毁后 handler 还活在全局 listeners 集合里每次消息推送都会调用已经销毁组件的方法内存和 CPU 双双遭殃。用组合式 API 写封装时一个顺手的方式是useWebSocket返回注册和注销两个方法在onUnmounted里配套调用。第二个泄漏来源是 ECharts 实例。图表组件在onMounted里echarts.initonUnmounted里必须chart.dispose()不然 zrender 的 canvas 对象和事件监听器都会留在内存中。这个错误比较隐蔽因为组件被销毁后你看不到报错只有内存面板里的实例数量越来越多。我做体检的标准流程是这样的打开 Memory 面板先记录一次堆快照操作页面一段时间再记录第二次对比两次快照中新增的对象。如果发现有大量 Detached DOM 节点或者同一组件的实例数量只增不减基本上就是上面这两类泄漏。6.2 渲染优化技巧从 20% CPU 降到 8%上线前做性能优化时我用 Performance 面板看了下主线程的占用发现两个明显的热点一是频繁的 DOM 操作二是 ECharts 的setOption太频繁。优化下来大屏整体的 CPU 占用从原先的 20% 降到了 8% 左右流畅度提升非常明显。具体做法有三条。第一条是合并数据更新。后端推送消息的频率可能一秒钟有 5-10 条但图表不需要每一条都立刻重绘。我用requestAnimationFrame做节流收集这一帧内的所有消息在下一帧开始时一次性处理let pendingData [] let scheduled false function onMessage(data) { pendingData.push(data) if (!scheduled) { scheduled true requestAnimationFrame(() { // 合并批量处理比如只渲染最新的一条或最后的绘制状态 handleBatch(pendingData) pendingData [] scheduled false }) } }第二条是列表虚拟化。告警滚动列表在数据量大时 DOM 节点会非常多我用了一个简单的虚拟列表只渲染当前可视区域内的 10 条告警上下各留一个缓冲条通过transform: translateY来控制偏移。这个方案比引入一个虚拟列表库轻量得多大屏场景足够用。第三条是 CSS 动画替代 JS 动画。告警闪烁、呼吸灯效果这类尽量用 CSSanimation而不是 JS 定时器因为 CSS 动画是在合成器线程上执行的不会占用主线程的 JS 执行时间。这是很多前端新手容易忽略的点。6.3 复盘做好实时大屏项目的几个底层能力这个项目做完回头复盘我认为大屏项目真正考验的不是某个框架熟不熟而是几个底层能力实时通信协议的清晰度。项目的质量上限在协议设计阶段就确定了。字段命名规范是否统一、消息序号、ack 机制、补拉逻辑是否提前设计清楚决定了联调阶段是要加班还是要早退。数据驱动视图的设计能力。大屏上所有视觉元素都是数据的呈现形式如果组件状态和数据流设计不清晰后面每加一个图表都要推翻重来。我这次通过 adapter 层和 Pinia store 统一管数据得到了立竿见影的收益。性能意识。大屏不是静态图场景而是长时间运行的实时页面内存泄漏和渲染开销问题放得很大。多花时间在性能面板上能提前发现将来现场演示时才会暴露的问题。客观说这篇文章里讲的核心方案大部分是我在业务中反复验证过的。举一个具体的例子心跳机制和断线补拉这套逻辑后来被团队内部沉淀成了一个可复用的ws-manager包其他项目直接拿来用大屏缩放的setupScale函数也被抽到公共 utils 里了。如果你也在做一个类似的实时数据可视化项目上面这些方案可以放心拿去用尤其是 WebSocket 那一套和 ECharts 增量更新这两个点处理好了大屏跑起来的稳定性会有明显提升。最后分享一个我自己的习惯做这类项目时准备一个 check list把断线重连、心跳、内存释放、性能探针这些点挨个过一遍比上线后反复调试高效得多。
