univer-node-backend

Univer Node.js 后端

本指南介绍如何在没有浏览器的 Node.js 环境中运行 Univer。适用于无头电子表格处理、自动生成报告、服务端公式计算和批量数据处理。

兼容性：本技能适用于 Univer v0.21.x / Univer Pro v0.20.x。根据 Univer 架构，Node.js 与浏览器支持是同构的。

前置条件：假定你熟悉 univer-integrate 技能（基础插件架构、Facade API、插件注册顺序）。本技能仅介绍 Node.js 特有的差异。

快速开始

1. 安装依赖

npm install @univerjs/core @univerjs/engine-formula @univerjs/sheets @univerjs/sheets-formula @univerjs/rpc-node

在 Node.js 中使用 Pro 功能：

npm install @univerjs-pro/license @univerjs-pro/engine-formula @univerjs-pro/sheets-pivot @univerjs-pro/collaboration-client-node

2. 在 Node.js 上创建 Univer 实例

import { LocaleType, Univer } from '@univerjs/core';
import { FUniver } from '@univerjs/core/facade';
import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula';
import { UniverSheetsPlugin } from '@univerjs/sheets';
import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula';
import { UniverSheetsFilterPlugin } from '@univerjs/sheets-filter';

// Facade side-effect imports for Node.js
import '@univerjs/sheets/facade';
import '@univerjs/engine-formula/facade';
import '@univerjs/sheets-formula/facade';
import '@univerjs/sheets-filter/facade';
import '@univerjs/sheets-numfmt/facade';

const univer = new Univer({
  locale: LocaleType.ZH_CN,
});

univer.registerPlugin(UniverFormulaEnginePlugin);
univer.registerPlugin(UniverSheetsPlugin);
univer.registerPlugin(UniverSheetsFormulaPlugin);
univer.registerPlugin(UniverSheetsFilterPlugin);

const univerAPI = FUniver.newAPI(univer);
const workbook = univerAPI.createWorkbook({});
const sheet = workbook.getActiveSheet();

sheet.getRange('A1').setValue({ v: 123 });
sheet.getRange('B1').setValue({ f: '=SUM(A1) * 6' });

console.log(workbook.save());

3. 用于公式计算的 Node.js 工作进程（可选）

对于繁重的公式计算任务，可将其交给一个派生进程处理：

// main.ts
import path from 'node:path';
import { LocaleType, Univer } from '@univerjs/core';
import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula';
import { UniverRPCNodeMainPlugin } from '@univerjs/rpc-node';
import { UniverSheetsPlugin } from '@univerjs/sheets';

const univer = new Univer({ locale: LocaleType.ZH_CN });

univer.registerPlugin(UniverFormulaEnginePlugin, { notExecuteFormula: true });
univer.registerPlugin(UniverSheetsPlugin);

const workerPath = path.join(__dirname, 'worker.js');
univer.registerPlugin(UniverRPCNodeMainPlugin, { workerSrc: workerPath });

// worker.js
import { LocaleType, Univer } from '@univerjs/core';
import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula';
import { UniverRPCNodeWorkerPlugin } from '@univerjs/rpc-node';
import { UniverSheetsPlugin } from '@univerjs/sheets';

const univer = new Univer({ locale: LocaleType.ZH_CN });

univer.registerPlugin(UniverSheetsPlugin, { onlyRegisterFormulaRelatedMutations: true });
univer.registerPlugin(UniverFormulaEnginePlugin);
univer.registerPlugin(UniverRPCNodeWorkerPlugin);

核心概念

浏览器与 Node.js 的差异

注意事项	浏览器	Node.js
UI 插件	必需（UniverUIPlugin、*-ui）	省略所有 *-ui 插件
渲染引擎	UniverRenderEnginePlugin	除非使用图表/形状，否则省略
RPC	UniverRPCMainThreadPlugin + Worker	UniverRPCNodeMainPlugin + fork()
工作进程插件	UniverRPCWorkerThreadPlugin	UniverRPCNodeWorkerPlugin
CSS 导入	必需	不需要
主题	来自 @univerjs/themes 的 defaultTheme	不需要

插件注册顺序（Node.js）

1. UniverLicensePlugin (Pro only)
2. Engine plugins (UniverFormulaEnginePlugin / UniverProFormulaEnginePlugin)
3. RPC (UniverRPCNodeMainPlugin, if using worker)
4. Unit core (UniverSheetsPlugin, UniverDocsPlugin)
5. Feature plugins (UniverSheetsFormulaPlugin, UniverSheetsFilterPlugin, etc.)
6. Pro features (UniverSheetsPivotTablePlugin, etc.)

Node.js Facade 导入

并非所有 Facade 导入都能在 Node.js 中使用。只能导入不依赖浏览器 API 的包：

// Safe in Node.js
import '@univerjs/core/facade';
import '@univerjs/sheets/facade';
import '@univerjs/engine-formula/facade';
import '@univerjs/sheets-formula/facade';
import '@univerjs/sheets-filter/facade';
import '@univerjs/sheets-numfmt/facade';
import '@univerjs/sheets-data-validation/facade';
import '@univerjs/sheets-conditional-formatting/facade';
import '@univerjs/sheets-hyper-link/facade';
import '@univerjs/sheets-thread-comment/facade';
import '@univerjs/sheets-drawing/facade';
import '@univerjs/sheets-sort/facade';
import '@univerjs/sheets-table/facade';
import '@univerjs/sheets-note/facade';

// Pro (safe in Node.js)
import '@univerjs-pro/sheets-pivot/facade';
import '@univerjs-pro/sheets-chart/facade';
import '@univerjs-pro/sheets-shape/facade';
import '@univerjs-pro/sheets-sparkline/facade';
import '@univerjs-pro/collaboration-client/facade';

// Unsafe in Node.js (depend on browser APIs)
// import '@univerjs/ui/facade';
// import '@univerjs/sheets-ui/facade';
// import '@univerjs/sheets-drawing-ui/facade';
// import '@univerjs/sheets-formula-ui/facade';

常见任务

批量生成报告

const workbook = univerAPI.createWorkbook({});
const sheet = workbook.getActiveSheet();

// Populate data from database
const rows = await db.query('SELECT * sales');
rows.forEach((row, i) => {
  sheet.getRange(i + 1, 0).setValue(row.date);
  sheet.getRange(i + 1, 1).setValue(row.amount);
});

// Add formula summary
const lastRow = rows.length;
sheet.getRange(lastRow + 1, 1).setValue({ f: `=SUM(B2:B${lastRow})` });

// Export snapshot
const snapshot = workbook.save();

加载并修改现有工作簿

const existingData = JSON.parse(fs.readFileSync('input.json', 'utf8'));
const workbook = univerAPI.createWorkbook(existingData);
const sheet = workbook.getActiveSheet();

sheet.getRange('A1').setValue('Updated');
fs.writeFileSync('output.json', JSON.stringify(workbook.save()));

服务端公式计算

// Without worker (simple workloads)
univer.registerPlugin(UniverFormulaEnginePlugin);

// With worker (heavy workloads)
univer.registerPlugin(UniverFormulaEnginePlugin, { notExecuteFormula: true });
univer.registerPlugin(UniverRPCNodeMainPlugin, { workerSrc: './worker.js' });

在服务端注册自定义函数

const formulaEngine = univerAPI.getFormula();
formulaEngine.registerFunction(
  'DISCOUNT',
  (price, percent) => price * (1 - percent / 100),
  'Calculate price after discount'
);

Pro Node.js 集成

如需在 Node.js 中使用 Univer Pro 功能（协作、透视、图表、形状），请参阅 references/node-pro-integration.md。

参考资料

• Node 插件注册表：references/node-plugin-registry.md — Node.js 的完整插件列表、注册顺序、工作进程配置，以及仅限浏览器的功能排除项
• Node 常见任务：references/node-common-tasks.md — 批量处理、JSON 导入/导出、公式计算模式、自定义函数、无头模式下的事件处理
• Pro Node.js 集成：references/node-pro-integration.md — Pro 公式引擎、协作客户端 Node、后端中的透视/图表/形状，以及服务端许可证设置