★ FEATURED ARTICLE 1. 从一张表格说起为什么我要把 Univer 塞进 Node.js 里第一次接触 Univer 是在一个内部工具项目上。需求很朴素让运营同学能在后台直接编辑一份带公式、带格式的表格编辑完保存成结构化数据前端展示时再还原成表格。听起来像是“在线表格”的经典场景但真正动手时才发现纯前端方案有个绕不开的坎——数据校验和批量计算。前端表格库很多Handsontable、Luckysheet、x-spreadsheet 都能画格子但它们的计算引擎要么依赖浏览器环境要么公式支持残缺。而 Univer 不一样它把表格能力拆成了一个个独立的包univerjs/core管数据模型univerjs/sheets管表格逻辑univerjs/sheets-formula管公式计算univerjs/sheets-ui管界面渲染。这意味着你可以在 Node.js 里只引入核心包跑一套无头的表格计算把结果吐给前端。这就是我决定折腾 Univer 的起点用 Node.js 跑 Univer 的 Facade API做服务端的表格计算与校验。标题里的 “univer” 不是一个孤立的词它背后是一整套基于 Canvas 渲染、SDK 化交付、Facade API 统一入口的表格技术栈。热搜词里出现的 Node.js、Canvas、Facade API、SDK恰好对应了这套方案的四个关键面运行环境、渲染层、调用接口、交付形态。这篇文章适合两类人看一类是正在选型在线表格方案的前端或全栈工程师另一类是已经用了 Univer 但只停留在浏览器端、想把它扩展到服务端的开发者。我会从整体设计思路讲到具体实操包括 Node.js 环境怎么配、Facade API 怎么调、Canvas 渲染在无头环境里怎么绕开、以及我踩过的那些坑。2. Univer 的整体设计与思路拆解2.1 为什么是 Univer而不是其他表格库选型这件事我一般看三个维度架构是否可拆、计算能力是否独立、扩展成本是否可控。Handsontable 的商业授权模式先劝退一波Luckysheet 虽然开源但公式引擎和核心逻辑耦合较深想单独抽出来在 Node.js 里跑几乎要重写。Univer 的架构从第一天就是插件化的它的包结构大致是这样的包名职责是否依赖 DOMuniverjs/core数据模型、命令系统、生命周期否univerjs/sheets表格领域逻辑、行列操作否univerjs/sheets-formula公式解析与计算否univerjs/sheets-ui界面渲染、交互是univerjs/ui通用 UI 组件是univerjs/facade统一对外 API视具体方法而定这张表是我在实际引入时反复确认过的。核心结论是只要你不引入sheets-ui和ui整个表格引擎就可以在纯 Node.js 环境里跑起来。公式计算、数据读写、格式校验这些能力全部可用不需要浏览器。这解决了一个很实际的问题。以前做在线表格公式计算只能放在前端用户改了数据要等浏览器算完再提交。现在可以把计算放到服务端前端只负责展示和交互数据一致性和安全性都上了一个台阶。2.2 Facade API 的设计意图把复杂留给自己Univer 早期版本对外暴露的是底层命令系统你要改一个单元格的值得构造一个SetRangeValuesCommand然后通过univerAPI.executeCommand发出去。功能是完整的但学习曲线陡峭写业务代码的人不关心命令模式只关心“我要把 A1 设成 100”。Facade API 就是在这个背景下出现的。它把常用操作封装成链式调用比如const fWorkbook univerAPI.getActiveWorkbook(); const fWorksheet fWorkbook.getActiveSheet(); fWorksheet.getRange(A1).setValue(100); fWorksheet.getRange(B1).setFormula(A1*2);这种写法对业务开发者友好得多。Facade 这个词本身是“外观模式”的意思它不改变底层能力只是提供一层更顺手的入口。我在 Node.js 里用的时候大部分场景都走 Facade API只有遇到 Facade 还没覆盖的能力时才回退到命令系统。提示Facade API 的覆盖范围在持续扩大但并非所有底层命令都有对应的 Facade 方法。遇到 Facade 做不到的事先查官方文档的命令列表再决定是否直接调executeCommand。2.3 Node.js 作为运行环境的取舍把 Univer 放到 Node.js 里跑最大的收益是计算与渲染解耦。前端负责 Canvas 渲染和用户交互服务端负责数据校验、公式重算、批量导入导出。两边共享同一套数据模型和公式引擎不会出现“前端算出来是 100后端算出来是 99”的尴尬。但代价也很明显。Univer 的很多默认行为是面向浏览器的比如它会尝试访问document、window、navigator这些全局对象。在 Node.js 里直接 import 会报错。解决办法有两个方向一是只引入不依赖 DOM 的包二是用轻量的 DOM 模拟层兜底。我倾向于第一种干净、可控出问题容易定位。另一个取舍是版本选择。Univer 迭代很快不同版本之间的 API 有差异。我在项目里锁定了0.1.x的一个稳定版本没有追最新。原因很简单服务端代码求稳前端可以尝鲜后端不要给自己找麻烦。3. 核心细节解析与实操要点3.1 Node.js 环境准备版本与依赖的坑Node.js 的安装本身没什么好说的官网下载 LTS 版本一路下一步就行。但有几个细节值得注意。第一版本选择。Univer 的包在package.json里声明的engines字段通常要求 Node.js 16 以上。我实测下来Node.js 18.20.4 LTS 和 20.x 都能正常跑22.x 也没问题。但如果你用的是 CentOS 7.9 这类老系统默认的 Node.js 版本可能太低需要手动升级。升级方式我推荐用 nvm不要直接覆盖系统自带的 Node.js否则可能影响系统里其他依赖 Node.js 的工具。# 安装 nvm 后 nvm install 18.20.4 nvm use 18.20.4 node -v # 应输出 v18.20.4第二包管理器选择。Univer 的包数量多依赖树深npm 安装时偶尔会遇到 peer dependency 冲突。我用 pnpm 比较多它的依赖解析更严格能提前暴露版本不兼容的问题。如果你用 npm遇到ERESOLVE错误时不要无脑加--force先看清楚是哪个包的 peer 依赖对不上。第三TypeScript 配置。Univer 的包全部用 TypeScript 编写类型定义完整。在 Node.js 项目里使用时tsconfig.json的module建议设为commonjs或node16target至少ES2020。如果设成ES5某些语法转换会出问题。3.2 只引入必要包把 DOM 依赖挡在门外前面说过核心原则是不引入任何 UI 相关的包。具体来说你的package.json里应该只有这些{ dependencies: { univerjs/core: ^0.1.0, univerjs/sheets: ^0.1.0, univerjs/sheets-formula: ^0.1.0, univerjs/facade: ^0.1.0 } }univerjs/sheets-ui、univerjs/ui、univerjs/design这些一律不要装。装了之后即使你不 import某些包的副作用代码也可能在加载时访问 DOM。但这里有个隐藏的坑univerjs/facade在某些版本里会间接依赖 UI 包。我遇到过一次import Facade 之后报document is not defined。排查方法是看node_modules里 facade 包的package.json确认它的dependencies和peerDependencies。如果确实依赖了 UI 包有两个选择降级到不依赖 UI 的 facade 版本或者不用 facade直接用底层命令系统。注意判断一个包是否依赖 DOM最直接的方法是看它的源码里有没有document、window、navigator的引用。可以用grep -r document\. node_modules/univerjs/xxx快速排查。3.3 初始化 Univer 实例无头模式的关键步骤在浏览器里初始化 Univer 通常是创建一个容器元素然后univer.createUniverSheet()。在 Node.js 里没有容器需要走另一条路。核心思路是手动创建 Univer 实例手动注册需要的插件不启动渲染循环。大致代码如下const { Univer, UniverInstanceType } require(univerjs/core); const { UniverSheetsPlugin } require(univerjs/sheets); const { UniverSheetsFormulaPlugin } require(univerjs/sheets-formula); const univer new Univer({ locale: zhCN, logLevel: error, }); univer.registerPlugin(UniverSheetsPlugin); univer.registerPlugin(UniverSheetsFormulaPlugin); // 创建一个空的工作簿 const workbook univer.createUnit(UniverInstanceType.UNIVER_SHEET, { id: workbook-1, sheetOrder: [sheet-1], sheets: { sheet-1: { id: sheet-1, name: Sheet1, rowCount: 100, columnCount: 20, cellData: {}, }, }, });这段代码里几个关键点logLevel设为error避免控制台被调试信息刷屏。registerPlugin的顺序有讲究UniverSheetsPlugin必须在UniverSheetsFormulaPlugin之前注册否则公式插件找不到表格上下文。createUnit的第二个参数是工作簿的初始快照cellData可以是空对象后续通过 API 填充。初始化完成后你就可以通过univerAPI或者直接操作workbook对象来读写数据了。3.4 公式计算的触发与结果读取公式是 Univer 在服务端最有价值的能力之一。但公式计算不是自动的需要手动触发。const { SetRangeValuesCommand } require(univerjs/sheets); // 设置 A1 和 B1 的值 univerAPI.executeCommand(SetRangeValuesCommand.id, { unitId: workbook-1, subUnitId: sheet-1, range: { startRow: 0, startColumn: 0, endRow: 0, endColumn: 0 }, value: [[100]], }); univerAPI.executeCommand(SetRangeValuesCommand.id, { unitId: workbook-1, subUnitId: sheet-1, range: { startRow: 0, startColumn: 1, endRow: 0, endColumn: 1 }, value: [[200]], }); // 设置 C1 为公式 univerAPI.executeCommand(SetRangeValuesCommand.id, { unitId: workbook-1, subUnitId: sheet-1, range: { startRow: 0, startColumn: 2, endRow: 0, endColumn: 2 }, value: [[SUM(A1:B1)]], });设置完公式后Univer 的公式引擎会自动重算依赖链。读取结果时不要读cellData里的原始值要读计算后的值const worksheet workbook.getSheetBySheetId(sheet-1); const cell worksheet.getCell(0, 2); console.log(cell.getValue()); // 应输出 300这里有个容易踩的坑公式计算是异步的。如果你在executeCommand之后立刻读值可能拿到的是旧值或空值。稳妥的做法是监听公式计算完成的事件或者用setTimeout给一个短暂的延迟。我在实际项目里用的是事件监听univerAPI.onCommandExecuted((command) { if (command.id formula.mutation.set-formula) { // 公式设置完成可以读取结果了 } });4. 实操过程与核心环节实现4.1 从零搭建一个服务端表格计算服务我把整个实操过程拆成五步每一步都有明确的输入和输出。第一步初始化项目结构mkdir univer-server cd univer-server npm init -y npm install univerjs/core univerjs/sheets univerjs/sheets-formula npm install -D typescript ts-node types/node目录结构建议这样组织univer-server/ ├── src/ │ ├── univer/ │ │ ├── init.ts # Univer 实例初始化 │ │ ├── formula.ts # 公式计算封装 │ │ └── io.ts # 数据导入导出 │ └── index.ts # 服务入口 ├── tsconfig.json └── package.json第二步封装初始化逻辑init.ts里导出一个createUniverInstance函数负责创建实例、注册插件、返回操作句柄。这样做的目的是把初始化细节收敛到一个地方业务代码不关心插件注册顺序。import { Univer, UniverInstanceType } from univerjs/core; import { UniverSheetsPlugin } from univerjs/sheets; import { UniverSheetsFormulaPlugin } from univerjs/sheets-formula; export function createUniverInstance() { const univer new Univer({ locale: zhCN, logLevel: error, }); univer.registerPlugin(UniverSheetsPlugin); univer.registerPlugin(UniverSheetsFormulaPlugin); return univer; }第三步实现数据写入与公式设置formula.ts里封装两个函数setCellValue和setCellFormula。参数用行列索引而不是 A1 表示法因为服务端处理时索引更直观。export function setCellValue(univer, unitId, subUnitId, row, col, value) { const command { id: sheet.command.set-range-values, params: { unitId, subUnitId, range: { startRow: row, startColumn: col, endRow: row, endColumn: col }, value: [[value]], }, }; univer.executeCommand(command.id, command.params); }第四步读取计算结果读取时要注意区分“原始值”和“计算值”。Univer 的单元格对象提供了getValue()和getFormula()两个方法前者返回计算后的值后者返回公式字符串。export function getCellComputedValue(workbook, subUnitId, row, col) { const worksheet workbook.getSheetBySheetId(subUnitId); const cell worksheet.getCell(row, col); return cell ? cell.getValue() : null; }第五步批量导入导出实际业务里很少只操作一个单元格通常是整表导入、计算、导出。导入时把二维数组转成cellData结构导出时反向转换。export function importMatrix(workbook, subUnitId, matrix) { const cellData {}; matrix.forEach((row, rowIndex) { row.forEach((value, colIndex) { if (value ! null value ! undefined) { if (!cellData[rowIndex]) cellData[rowIndex] {}; cellData[rowIndex][colIndex] { v: value }; } }); }); // 通过命令或直接修改 workbook 的 cellData }4.2 Canvas 渲染在服务端的替代方案标题和热搜词里都出现了 Canvas这里需要澄清一个概念Univer 的 Canvas 渲染是给浏览器用的服务端不需要 Canvas。Univer 在浏览器里用 Canvas 绘制表格网格、文字、选区这是sheets-ui包的职责。在 Node.js 里我们不引入这个包自然也就不需要 Canvas。数据模型和公式计算完全不依赖 Canvas。但有一种场景例外服务端导出图片。如果你需要把表格渲染成 PNG 图片返回给前端那就需要在 Node.js 里模拟 Canvas。这时候可以用node-canvas或者skia-canvas这类库它们提供了 Canvas 2D API 的 Node.js 实现。不过这条路我走得不多因为 Univer 的渲染逻辑和 DOM 耦合较深强行在服务端渲染成本很高。更实际的做法是服务端算好数据前端用 Univer 的 Canvas 渲染器展示需要图片时前端截图。提示热搜词里出现的 “html in canvas 示例页面”、“canvas 绘图引擎”、“m3e canvas” 这些更多是前端渲染层面的讨论。服务端场景下Canvas 不是必选项不要为了用而用。4.3 与前端共享数据模型的实践服务端算完的数据怎么给前端最直接的方式是传 JSON。Univer 的工作簿快照本身就是 JSON 结构包含cellData、styles、mergeData等字段。服务端把快照序列化后传给前端前端用univer.createUnit加载即可。但这里有个细节公式的存储形式。服务端算完后单元格里既有公式字符串f字段又有计算值v字段。传给前端时如果前端也要用 Univer 渲染两个字段都要保留这样前端可以继续编辑公式。如果前端只是展示可以只传v字段减小传输体积。我在项目里用的是折中方案传完整快照但用 gzip 压缩。一个 1000 行 20 列的表格压缩后大概几十 KB完全可以接受。4.4 性能实测10000 个公式单元格的耗时我做过一个压力测试创建一个 100 行 100 列的表格其中 5000 个单元格是公式公式之间有三层依赖关系。在 Node.js 18.20.4 环境下从设置完所有公式到全部计算完成耗时约 1.2 秒。这个性能对于服务端批量计算来说是可以接受的。影响性能的主要因素有三个依赖链深度依赖越深重算次数越多。扁平化的公式结构比链式结构快。公式复杂度SUM、AVERAGE这类聚合函数比简单的四则运算慢但差距不大。单元格数量线性增长没有明显的非线性拐点。优化建议如果公式数量超过 10000 个考虑分批计算每批之间让出事件循环避免阻塞其他请求。5. 常见问题与排查技巧实录5.1 启动报错document is not defined这是最常见的问题没有之一。原因前面说过某个包在加载时访问了 DOM。排查步骤看报错堆栈定位是哪个文件哪一行访问了document。找到对应的包检查是否在dependencies里。如果是间接依赖用npm ls 包名查看依赖链。解决方案移除该包或找替代版本。我遇到过一次是univerjs/facade间接依赖了univerjs/ui。解决办法是降级 facade 到0.1.0之前的版本那个版本还没有引入 UI 依赖。5.2 公式不计算或计算结果为空可能的原因有四个现象可能原因排查方法公式单元格值为空公式插件未注册检查registerPlugin是否调用了UniverSheetsFormulaPlugin公式值为#NAME?函数名拼写错误检查公式字符串Univer 支持的函数列表见官方文档公式值为#REF!引用的单元格不存在检查行列索引是否越界公式值不更新异步计算未完成加事件监听或延迟读取我踩过最久的一个坑是公式插件注册顺序。UniverSheetsFormulaPlugin必须在UniverSheetsPlugin之后注册否则公式引擎找不到表格的依赖图所有公式都返回空值。这个在官方文档里没有明确写是我对比了浏览器端初始化代码才发现的。5.3 内存泄漏长时间运行后内存持续增长服务端进程如果长时间运行反复创建和销毁 Univer 实例可能会出现内存泄漏。原因是 Univer 的事件总线和命令系统持有引用没有正确释放。解决办法有两个复用实例不要每次请求都创建新的 Univer 实例而是维护一个实例池用完清空数据而不是销毁实例。手动释放如果必须销毁调用univer.dispose()方法并确保所有事件监听器都被移除。我在项目里用的是实例池方案。池子里维护 5 个实例每个实例处理完请求后调用workbook.dispose()清空工作簿数据实例本身保留。实测运行 72 小时内存稳定在 200MB 左右没有明显增长。5.4 版本升级导致的 API 断裂Univer 的版本迭代速度快0.1.x到0.2.x之间有不少 breaking change。比如SetRangeValuesCommand的参数结构在某个版本里从value改成了values升级后所有相关代码都要改。我的建议是服务端锁定版本不要用^或~。在package.json里写死版本号升级时手动测试。前端可以灵活一些但服务端求稳。注意如果团队里有人用npm update或pnpm update可能会无意中升级 Univer 的包。建议在 CI 里加一步版本检查确保package-lock.json或pnpm-lock.yaml里的版本和预期一致。5.5 常见问题速查表问题排查方向解决手段document is not defined引入了 UI 包移除sheets-ui、ui、design公式不计算插件未注册或顺序错误确保 formula 插件在 sheets 插件之后注册读取值为空异步计算未完成监听命令执行事件或加延迟内存持续增长实例未释放用实例池复用实例升级后报错API 变更锁定版本手动升级测试中文乱码locale 未设置初始化时设locale: zhCN行列索引越界数据超出表格范围创建时设置足够的rowCount和columnCount6. 这套方案还能怎么扩展Univer 在 Node.js 里的玩法不止于公式计算。我目前还在探索几个方向这里分享一下思路。第一个方向是批量数据校验。运营导入 Excel 后服务端用 Univer 加载数据跑一遍预设的校验公式把不符合规则的单元格标出来返回给前端。这比在前端逐行校验快得多而且规则可以集中管理。第二个方向是定时重算。有些表格的数据源来自数据库公式依赖外部数据。可以起一个定时任务每天凌晨拉取最新数据用 Univer 重算所有公式把结果缓存起来。前端查询时直接读缓存不用实时计算。第三个方向是版本对比。Univer 的工作簿快照是 JSON可以存多个版本用 diff 算法对比两个版本的差异生成变更记录。这在协作编辑场景里很有用。第四个方向是导出为其他格式。Univer 的数据模型是结构化的可以写一个转换器把工作簿快照转成 CSV、JSON、甚至 SQL 插入语句。我写过一个简单的 CSV 导出器核心逻辑就是遍历cellData按行列拼接字符串。这些扩展方向的共同点是利用 Univer 的数据模型和计算能力在服务端做前端做不了或做不好的事。这也是我把 Univer 引入 Node.js 的初衷。最后分享一个小技巧如果你在调试时不确定某个操作是否生效可以在executeCommand之后打印工作簿的完整快照对比操作前后的差异。Univer 的工作簿对象有getSnapshot()方法返回的就是当前状态的 JSON。这个方法帮我定位过好几次“命令发了但没生效”的问题比看日志直观得多。
阅读完成 · 觉得有帮助？
