企业官网建设流程全解析

Univer 全栈办公 SDK：插件组合、Preset 快速集成与跨平台兼容指南

【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer

本文基于 Univer 仓库中的西班牙语 README（docs/readme/es-ES.md）展开，系统讲解 Univer 这一「全栈、同构（isomorphic）办公 SDK」的定位与核心特性，并完整覆盖其 Plugin Mode 与 Preset Mode 两种初始化方式的可复制代码、跨平台兼容边界、开源与商业（Pro）能力划分，以及 monorepo 的目录结构与本地开发流程。读完后，你将能够在自己的产品中集成 Univer Sheets/Docs，并理解其插件化架构在源码层面的真实组成方式。

一、Univer 是什么：构建自己的生产力表面，而非托管应用

Univer 是一个面向 Web 与 Server 的开源全栈框架，用于创建和编辑电子表格、文字处理文档和演示文稿。它提供创建生产力体验所需的「积木」：插件化架构、基于 Canvas 的渲染、独立的公式引擎，以及一套在浏览器和 Node.js 中都能工作的 Facade API。

按照 README 的表述，Univer 的定位不是「一个托管的在线表格应用」，而是一个 SDK——你不需要接受它固定的 UI 或托管服务，而是把能力集成进自己的产品。典型适用场景包括：

• 在 SaaS、内部工具、BI 流程或 AI 应用中集成电子表格/文档编辑；
• 在服务器端用与浏览器相同的架构运行工作簿/文档处理（Headless）；
• 通过插件按需组合功能，或用 Preset 快速起步；
• 通过自定义插件、命令（Command）、服务（Service）、UI 组件和 Facade API 扩展行为。

README 用六个要点概括了它的亮点，这里完整保留其信息量：

源码印证：核心类与单元注册机制

从 核心类定义 可以看到，Univer类基于依赖注入（DI）构建：构造函数创建 Injector，并将theme、darkMode、locales、locale、region、direction、logLevel等配置分发到对应的 ThemeService、LocaleService、RegionService、ILogService。其中UNIVER_SHEET、UNIVER_DOC、UNIVER_SLIDE三种单元类型分别绑定Workbook、DocumentDataModel、SlideDataModel构造器（univer.ts 单元注册）——这正是「同一个 SDK 承载表格、文档、演示」三种表面的底层机制。

IUniverConfig接口（univer.ts）声明了实例级配置项，对集成方尤其有用的包括：

override是理解 Univer「可替换性」的关键：例如 createUniver 实现 中，开启collaboration: true时会把本地的IUndoRedoService、IAuthzIoService、IMentionIOService覆盖为null，为协同场景预留注入点。

二、快速开始：Plugin Mode（完整产品覆盖 + 精确控制）

README 的 Plugin Mode 快速开始是本文的核心实操内容。该模式给你对「装哪些包、导入哪些样式、如何合并 locale、如何注册 Facade API、如何传插件配置」的低层控制，适合需要精确控制包体积与组合方式的生产环境。

2.1 安装依赖

pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/sheets @univerjs/sheets-formula @univerjs/sheets-formula-ui @univerjs/sheets-numfmt @univerjs/sheets-numfmt-ui @univerjs/sheets-ui @univerjs/ui

2.2 初始化代码（完整可复制）

import { LocaleType, mergeLocales, Univer } from '@univerjs/core' import { FUniver } from '@univerjs/core/facade' import DesignEnUS from '@univerjs/design/locale/en-US' import { UniverDocsPlugin } from '@univerjs/docs' import { UniverDocsUIPlugin } from '@univerjs/docs-ui' import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US' import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula' import { UniverRenderEnginePlugin } from '@univerjs/engine-render' import { UniverSheetsPlugin } from '@univerjs/sheets' import SheetsEnUS from '@univerjs/sheets/locale/en-US' import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula' import SheetsFormulaEnUS from '@univerjs/sheets-formula/locale/en-US' import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui' import SheetsFormulaUIEnUS from '@univerjs/sheets-formula-ui/locale/en-US' import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt' import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui' import SheetsNumfmtUIEnUS from '@univerjs/sheets-numfmt-ui/locale/en-US' import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui' import SheetsUIEnUS from '@univerjs/sheets-ui/locale/en-US' import { UniverUIPlugin } from '@univerjs/ui' import UIEnUS from '@univerjs/ui/locale/en-US' import '@univerjs/design/lib/index.css' import '@univerjs/ui/lib/index.css' import '@univerjs/docs-ui/lib/index.css' import '@univerjs/sheets-ui/lib/index.css' import '@univerjs/sheets-formula-ui/lib/index.css' import '@univerjs/sheets-numfmt-ui/lib/index.css' import '@univerjs/engine-formula/facade' import '@univerjs/ui/facade' import '@univerjs/sheets/facade' import '@univerjs/sheets-ui/facade' import '@univerjs/sheets-formula/facade' import '@univerjs/sheets-numfmt/facade' const univer = new Univer({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( DesignEnUS, UIEnUS, DocsUIEnUS, SheetsEnUS, SheetsUIEnUS, SheetsFormulaEnUS, SheetsFormulaUIEnUS, SheetsNumfmtUIEnUS, ), }, }) univer.registerPlugin(UniverRenderEnginePlugin) univer.registerPlugin(UniverFormulaEnginePlugin) univer.registerPlugin(UniverUIPlugin, { container: 'app' }) univer.registerPlugin(UniverDocsPlugin) univer.registerPlugin(UniverDocsUIPlugin) univer.registerPlugin(UniverSheetsPlugin) univer.registerPlugin(UniverSheetsUIPlugin) univer.registerPlugin(UniverSheetsFormulaPlugin) univer.registerPlugin(UniverSheetsFormulaUIPlugin) univer.registerPlugin(UniverSheetsNumfmtPlugin) univer.registerPlugin(UniverSheetsNumfmtUIPlugin) const univerAPI = FUniver.newAPI(univer) univerAPI.createWorkbook({})

这段代码中几个容易踩坑的点：

1. 样式必须逐包导入：@univerjs/design、@univerjs/ui以及每个*-ui包的lib/index.css都需要显式导入，缺少任何一个都会出现样式错乱。
2. locale 需要mergeLocales合并：每个 UI 包各自携带词条，mergeLocales把它们合并进locales[LocaleType.XXX]，漏合并的包会显示英文回退文案。
3. /facade副作用导入不可省略：import '@univerjs/xxx/facade'是各包向全局 Facade 注册类型与入口的方式，省略后univerAPI上对应方法/类型会缺失。
4. container是字符串 id：UniverUIPlugin的container: 'app'指向页面中 id 为app的 DOM 容器。

仓库中的本地示例 examples/src/sheets/main.ts 展示了同一模式的「完整版」：在核心 12 包之上继续注册了UniverSheetsFilterPlugin、UniverSheetsSortPlugin、UniverSheetsTablePlugin、UniverSheetsNotePlugin、UniverSheetsHyperLinkPlugin、UniverSheetsDataValidationPlugin、UniverSheetsConditionalFormattingPlugin、UniverThreadCommentPlugin、UniverNetworkPlugin，以及 Vue3 / Web Component 适配器和 RPC 主线程插件，并使用批量注册 APIuniver.registerPlugins([...])。该示例还演示了插件级配置，例如UniverSheetsUIPlugin的ribbonType: 'grid'、customFontFamily，以及UniverSheetsPlugin的autoHeightForMergedCells: true。

三、快速开始：Preset Mode（更少配置的策展式集合）

对于 Sheets、Docs 和 Node 等受支持的 profile，README 推荐用 Preset Mode 获得更短的初始化代码。Preset 是「策展过的插件集合」，已经内置了所需的 Facade API 注册和样式导入。

3.1 安装与初始化

pnpm add @univerjs/presets @univerjs/preset-sheets-core

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core' import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US' import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets' import '@univerjs/preset-sheets-core/lib/index.css' const { univerAPI } = createUniver({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales(UniverPresetSheetsCoreEnUS), }, presets: [ UniverSheetsCorePreset({ container: 'app', }), ], }) univerAPI.createWorkbook({})

页面中需要一个挂载容器：

<div id="app" style="height: 100vh"></div>

3.2createUniver底层做了什么

阅读 presets/src/preset.ts 可以确认createUniver的完整行为链：

1. 以默认logLevel: LogLevel.WARN创建Univer实例（用户传入的配置会覆盖默认值）；
2. 遍历所有presets，按pluginName去重收集插件——后声明的 Preset 若包含同名插件，会替换先声明的；
3. 再处理显式传入的plugins，若与 Preset 已注册的插件重名会直接抛错（Plugin xxx already registered by presets or other ways!），防止重复注册带来隐患；
4. 最后用FUniver.newAPI(univer)生成 Facade 实例，并以{ univer, univerAPI }一并返回。

3.3UniverSheetsCorePreset内部注册的插件清单

UniverSheetsCorePreset 实现 揭示了「curated collection」的具体含义——它内部注册了：UniverNetworkPlugin、UniverDocsPlugin、UniverRenderEnginePlugin、UniverUIPlugin、UniverDocsUIPlugin、UniverFormulaEnginePlugin、UniverSheetsPlugin、UniverSheetsUIPlugin、UniverSheetsNumfmtPlugin、UniverSheetsNumfmtUIPlugin、UniverSheetsFormulaPlugin、UniverSheetsFormulaUIPlugin，并在传入workerURL时自动追加UniverRPCMainThreadPlugin（Web Worker 模式）。

其中两个值得注意的细节：

• workerURL与公式计算位置的联动：一旦传入workerURL（useWorker = true），UniverSheetsPlugin与UniverFormulaEnginePlugin都会收到notExecuteFormula: true——即主线程不再执行公式，计算交给 Worker，这正是「Web Worker/RPC 模式」的实现方式；
• 配置透传粒度：IUniverSheetsCorePresetConfig从 UI 配置中Pick出container | header | toolbar | ribbonType | menu | contextMenu | disableAutoFocus | customFontFamily，从 Sheets UI 配置中Pick出formulaBar | footer，并暴露docs、sheets（如isRowStylePrecedeColumnStyle、autoHeightForMergedCells、freezeSync）、formula（如function、initialFormulaComputing）三个子配置块，默认container为'app'。

3.4 多 Preset 组合的真实示例

仓库示例 examples/src/preset-sheets-core/main.ts 展示了 11 个 Preset 叠加的写法：UniverSheetsCorePreset()、UniverSheetsDrawingPreset()、UniverSheetsConditionalFormattingPreset()、UniverSheetsFilterPreset()、UniverSheetsHyperLinkPreset()、UniverSheetsDataValidationPreset()、UniverSheetsFindReplacePreset()、UniverSheetsNotePreset()、UniverSheetsSortPreset()、UniverSheetsTablePreset()、UniverSheetsThreadCommentPreset()，同时用mergeLocales合并各自 locale 包，并通过plugins: [ImportCSVButtonPlugin]追加自定义插件——这印证了 Preset 与自定义插件可以混用，但自定义插件不能与 Preset 内置插件重名。

仓库presets/packages/目录下当前提供的 Preset 覆盖：Docs 侧的preset-docs-core、preset-docs-drawing、preset-docs-hyper-link、preset-docs-thread-comment，Sheets 侧的preset-sheets-core、preset-sheets-conditional-formatting、preset-sheets-data-validation、preset-sheets-drawing、preset-sheets-filter、preset-sheets-find-replace、preset-sheets-hyper-link、preset-sheets-note、preset-sheets-sort、preset-sheets-table、preset-sheets-thread-comment，以及 Node 侧的preset-docs-node-core与preset-sheets-node-core。

四、三种模式的选型对照

README 给出了 Plugin / Preset / Headless 三种模式的选择建议，这里完整保留并补充仓库内的起点路径：

两条重要约束：

• 版本必须对齐：所有@univerjs/*包应保持同一版本；若使用 Univer Pro 包，@univerjs-pro/*的版本也要与 OSS 包对齐。
• API 稳定性预期：关于 stable / experimental / internal / deprecated 的分级与 breaking change 规则，见 docs/API_STABILITY.md。

五、跨平台兼容性边界（以当前仓库为准）

README 的 Compatibility 一节明确给出了以下兼容预期，适用前提是按当前仓库代码构建的版本：

• 浏览器运行时：Univer 以 Chrome 88 为编译目标，预期可运行于 Edge>=88、Firefox>=90、Chrome>=88、Safari>=14.1、Electron>=12。
• Polyfill 依赖：Univer 依赖Intl.Segmenter（用于文本分段渲染）。若目标浏览器或运行时不包含该 API，需要自行引入 polyfill（README 给出@formatjs/intl-segmenter作为示例）。
• 构建工具：推荐 Vite、esbuild 或 Webpack 5。若构建工具不支持package.json的exports字段（Webpack 4 的常见情况），可能需要额外配置路径映射。
• React 版本：视图层基于 React 18 构建，正式支持 React 18 与 19，并对 React 16.9+ 与 17 提供最低兼容。仓库根 package.json 中提供了use:react16/use:react19脚本（基于 scripts/react-version-manager.mts）用于在开发环境切换 React 版本验证兼容性。
• Node.js：Headless Univer 支持 Node.js>=18.17.0；而开发本 monorepo 本身需要 Node.js>=22.18（与根 package.json 中devEngines.runtime的>=22.18声明一致）。

六、能力矩阵：你可以构建什么

README 按六个领域划分了「开源能力」与「Univer Pro 扩展」，这是评估 OSS 边界的权威口径：

README 同时说明：Sheets 是目前最成熟的产品表面，Docs 与 Slides 共享 Univer 架构并在同一 SDK 中持续演进。

七、开源与 Pro 的边界原则

本仓库包含 Univer 的开源核心与第一方 OSS 插件；Univer Pro 作为商业扩展层独立开发，覆盖高级产品表面、协同、服务端能力与企业集成。两者按类别的划分（开源侧提供 SDK 核心、插件系统、渲染引擎、公式引擎、Facade API、主题、i18n 与框架适配器；Pro 侧提供协同、导入导出、打印、图表、服务端服务等）在 README 中有完整表格，此处不再重复，重点给出其「分离原则」，这部分对判断 bug 归属和文档可信度很实用：

• 本仓库的 OSS 包在 Apache-2.0 许可下自身即可独立可用，Univer Pro 是可选的，使用 OSS 包的公共 API 不依赖 Pro；
• OSS 包中的 bug、回归与安全问题的报告与修复都在 OSS 仓库进行，即使存在相关的 Pro 功能；
• OSS 文档不应暗示 Pro-only 能力可用，Pro-only 的 API、包与部署路径必须显式命名；
• 当某个 OSS 功能存在 Pro 增强时，OSS 行为仍需独立成文，让用户无需阅读商业文档即可评估开源范围。

许可信息：LICENSE，Apache-2.0。

八、仓库结构导航（Repository Guide）

README 给出的顶层目录职责如下，可作为深入源码的入口地图：

. ├── packages/ 核心包、引擎、文档类型、UI 插件与功能插件 ├── examples/ 浏览器与 Node.js 本地演示，用于开发 ├── common/ 内部共享工具、mock 数据、storybook 与工具链 ├── e2e/ Playwright 测试与视觉对比测试 ├── tests/ 附加集成测试工程（如 formula-integration） └── docs/ 架构笔记、图片与仓库本地文档

各包的 README 位于 packages/ 下对应包目录内。仓库内与主题强相关的本地文档入口：

• docs/ISOMORPHIC.md：如何分离浏览器逻辑、Node.js、UI 与共享插件——理解 Headless 与 Web Worker 架构的必读文档；
• docs/NAMING_CONVENTION.md：文件、目录、接口、插件、命令与 DI token 的命名约定；
• docs/CONTRIBUTING-FACADE.md：FUniver、FWorkbook、FRange等 Facade 类的设计预期；
• docs/FIX_MEMORY_LEAK.md：Univer 实例常见的内存泄漏模式与排查流程；
• docs/tldr/：公式引擎、Web Worker、权限、选区架构与 ref-range 行为的简要架构笔记；
• docs/API_STABILITY.md：API 稳定性政策。

九、本地开发：环境要求与命令

开发本仓库（注意：这里是「开发 Univer 本身」的要求，高于集成使用要求）需要：

• Node.js>=22.18
• pnpm>=11（根 package.json 锁定packageManager: pnpm@11.22.0）

获取并启动：

git clone https://gitcode.com/GitHub_Trending/un/univer cd univer pnpm install pnpm dev

常用命令（均已在根 package.json 的scripts中可验证）：

此外根脚本还提供coverage（50% 并行的覆盖率统计）、dev:e2e、build:demo、analyze:build等辅助命令，贡献前请先阅读 CONTRIBUTING.md。

十、给贡献者的延伸阅读与生态

在改动核心代码之前，README 建议通读前文「仓库结构导航」一节列出的本地文档，尤其是 docs/ISOMORPHIC.md（同构分层）与 docs/tldr/ 下的架构速记。生态侧，除本 monorepo 外，官方还维护 Preset 集合（即本仓库 presets/ 目录）、面向 AI Agent 的 SDK 技能集（univer-sdk-skills）、MCP 集成（univer-mcp）以及独立文档站与 API 参考站；参与社区前请阅读 CODE_OF_CONDUCT.md，发现安全问题请按 SECURITY.md 的流程处理。

小结

• 选型：需要精确控制包组合与运行时组合 → Plugin Mode；需要最快获得可运行的 Sheets/Docs/Node 应用 → Preset Mode；需要无 UI 的服务端处理 → Headless（Node>=18.17.0）。
• 初始化要点：Plugin Mode 下样式、locale、/facade三件套缺一不可；Preset Mode 下createUniver会做插件去重、重名抛错，并自动包裹出univerAPI。
• 边界：所有@univerjs/*包保持同版本；OSS 能力以仓库packages/与presets/实际内容为准确，Pro 能力在文档中独立标注。

【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer