1. 三个名字背后其实是三种完全不同的“在线编辑”方案先说点实际的。很多人第一次看到“unver、jsspredsheet、onlyoffice”这几个词放在一起会以为它们是同类产品对比。其实不是Univer没错你搜到的 unver 就是它只是经常被缩写或者拼错、Jspreadsheet同样jsspredsheet 是它的常见笔误和 OnlyOffice虽然都做在线编辑但做的事情完全不同。Univer 是一个开源的表格式办公套件定位有点像 Google Sheets 的本地化替代但它不是让你访问一个网站来用而是给你一套组件你可以把它嵌到自己的系统里实现单元格编辑、公式计算、条件格式、筛选、图表甚至协同编辑整个渲染是基于 Canvas 的所以用起来比传统 DOM 表格流畅很多。Jspreadsheet 则是一个更轻量的 JavaScript 数据表格插件依赖 jQuery主打的是快速生成可编辑的数据网格。它更适合做管理后台里的那种“在线录入表格”而不是一个完整的 Office 套件。它的体积小、上手快但功能深度远不如 Univer 或 OnlyOffice。OnlyOffice 是最重的一个它是一整套办公套件包含文本编辑器、电子表格、演示文稿并且带服务端。你部署了 OnlyOffice Document Server 之后通过 API 就能在自己的业务系统里打开 docx、xlsx、pptx实现多人实时协同编辑。它的核心价值在于“兼容 Office 格式”而 Univer 和 Jspreadsheet 更偏“前端交互”。所以你首先要搞清楚自己要解决什么问题是想在自己的网页里做一张可编辑的表格还是想做一个正经的在线文档协同系统这两种需求的选型方向完全不同。我最初接触这三样东西是因为要给客户的内部系统加一个在线预览和编辑 xlsx 的功能。当时我先试了 Jspreadsheet发现它处理大表格性能不错但一碰到 Excel 自带的复杂样式、公式跨表引用就力不从心。然后试了 Univer它在表格内核上做得确实更接近 Excel但依然没法原生打开 xlsx 文件并保留所有元素。最后才回过头认真研究 OnlyOffice 的文档服务。这一篇就把我自己的初步实践过程写清楚尤其是 OnlyOffice 的 Docker 镜像安装、协同编辑接入以及很多人搜过的那个有点奇怪的参数assemblyFormatAsOrigintrue到底是怎么回事。2. 搭建 OnlyOffice 文档服务器Docker 镜像安装的前前后后2.1 为什么第一步就走 Docker 镜像安装OnlyOffice 有两条部署路线一条是装全家桶Community Server Document Server一条是只装 Document Server。全家桶带项目管理、CRM、邮件这些协作功能看起来功能很全但对于只想在自己系统里嵌入在线编辑的开发者来说太重了。我实际测试下来只部署 Document Server 就够了它专门负责文档的保存、转换、协同编辑对外提供 API。而 Document Server 最省事的安装方式就是 Docker 镜像。你不需要在一台空机器上手动装 PostgreSQL、Redis、RabbitMQ、Nginx 这些依赖镜像里全都有。你要做的只是把容器跑起来把数据卷挂出来把端口映射好。如果你是从零开始且没有太多服务器运维经验我强烈建议直接用 Docker。OnlyOffice 官方提供的文档里写的安装步骤也是默认以 Docker 为主的社区里遇到安装问题十有八九也是围绕 Docker 环境讨论。2.2 最简部署命令和参数说明先看一下我最开始用的最简启动命令sudo docker run -i -t -d -p 80:80 --restartalways \ -v /app/onlyoffice/DocumentServer/logs:/var/log/onlyoffice \ -v /app/onlyoffice/DocumentServer/data:/var/www/onlyoffice/Data \ -v /app/onlyoffice/DocumentServer/lib:/var/lib/onlyoffice \ -v /app/onlyoffice/DocumentServer/db:/var/lib/postgresql \ onlyoffice/documentserver:latest解释一下几个关键点-p 80:80是把容器里的 80 端口映射到宿主机 80 端口。如果你的 80 端口已经被 Nginx 占用可以改成-p 8080:80后面访问地址就带端口。--restartalways保证服务器重启后容器自动拉起这个很重要不然后面隔三差五发现服务挂了。数据卷必须挂。/var/log/onlyoffice是日志目录排查安装问题全靠它/var/www/onlyoffice/Data是配置数据/var/lib/postgresql是数据库目录不挂的话容器一删所有文档元数据都没了。启动之后在浏览器访问http://你的服务器IP如果能看到一个“ONLYOFFICE Document Server”的欢迎页说明基本装好了。接下来就可以用/web-apps/apps/api/documents/api.js这个入口来对接前端的 JS API 了。我后来在生产环境里实际用的命令比这个多加了几个参数比如时区、JWT 密钥、内存限制。这里有一个容易忽略的点OnlyOffice Document Server 对系统内存有要求官方建议至少 2GB如果你在低配机器上强行跑文档转换时很容易崩。查看容器日志时如果看到内存相关的报错优先把内存升上去不要先怀疑代码。镜像安装的优点是可以省去手动初始化数据库的步骤缺点恰恰是出了问题不容易看到底层所以日志目录一定要提前规划好后面排查安装问题全靠它。2.3 常见安装问题端口冲突、域名校验、文档转换失败我在搭建过程中和后来帮朋友排查时最常见的安装问题基本集中在下面几类我用表格列一下现象可能原因处理办法容器启动了但页面打不开宿主机 80 端口被其他服务占用换一个宿主端口映射比如-p 8081:80并确认防火墙放行打开欢迎页正常但预览文档一直转圈服务器无法访问自身生成的下载链接检查回调 URL 配置确保前端传的document.url能被 Document Server 访问到这个“自我访问”问题在内网部署时极其常见上传 docx 后显示“未找到文件”容器内部 DNS 无法解析外部下载地址给容器配置 DNS 或直接用外网可访问的 URL不能填localhost能打开文档但保存失败JWT 密钥不一致前端初始化DocEditor时配置的token和 Document Server 环境变量里的JWT_SECRET必须一致转换耗时长或失败服务器内存不足或目标格式不受支持提高内存、排查日志确认格式是否在支持列表内这里面我特别想强调“文档转换失败”这一条。OnlyOffice 在前端展示 docx、xlsx 时并不是直接把原始文件拿来显示而是会先转换排版和内部格式。如果 Document Server 所在服务器访问不到文件 URL转换必然失败。很多人在本地联调时用http://localhost传 URLDocument Server 在容器里当然访问不到宿主机的 localhost。正确做法是在同一局域网内直接用宿主机 IP或者把文件转成 base64 走file字段。还有一类问题修改了 JWT_SECRET 之后旧的容器还是用自己的密钥导致前端一直报鉴权失败。这时候不要只改配置要重启容器并清一下 Redis 缓存。OnlyOffice 的 JWT 机制排查起来很绕建议一开始就统一用一个固定的强密钥前后端、环境变量保持一致别频繁换。3. 在线协同编辑接入从 API 初始化到assemblyFormatAsOrigintrue3.1 前端接入的完整套路OnlyOffice 在线协同编辑不是一个纯前端组件它需要你的业务系统把文档信息告诉 Document Server由 Document Server 负责加载文档、分发给各个在线用户。前端要做的事情其实很集中在页面引入https://你的服务器地址/web-apps/apps/api/documents/api.js。构造一个配置对象包含文档类型、文档 URL、权限、编辑器模式、回调地址等。初始化new DocsAPI.DocEditor(placeholder, config)。一个最小可用的配置大致长这样const docEditor new DocsAPI.DocEditor(docs-container, { document: { fileType: xlsx, key: unique-document-key-001, title: 销售统计表.xlsx, url: http://宿主机IP/example.xlsx, }, documentType: cell, editorConfig: { mode: edit, callbackUrl: http://宿主机IP/callback, user: { id: user-001, name: 张三, }, }, width: 100%, height: 100%, });有几个细节值得注意document.key是一个业务系统自己维护的文档唯一标识。OnlyOffice 用它做缓存判断如果同一个 key 的文档内容变了你需要更新 key否则服务端可能不会重新加载新内容。很多人改了文件但界面上还是旧的多半是 key 没有更新。document.url必须是 Document Server 能访问到的地址。如果你的文件在业务系统内网Document Server 也在同一内网直接填内网 IP 就行如果用公网服务器就要填能被公网访问的 URL。editorConfig.user是当前编辑人的身份。协同编辑时多人同时打开同一文档就是靠这个 user 区分不同用户的头像和光标。callbackUrl是 Document Server 在保存文档时通知你业务系统的地址。如果你想把编辑后的文档存回自己的服务器必须在回调接口里接收数据并做处理否则文档只保存在 OnlyOffice 的临时目录里。3.2assemblyFormatAsOrigintrue到底是干嘛的这个参数在 OnlyOffice 的讨论区里出现频率很高尤其是一些搜索热词里直接和 onlyoffice 放在一起。它最初出现在 Document Server 的内部转换请求接口里作用简单说就是让文档在转换和渲染时尽量以原始格式的规则来处理而不是强制转换成 OnlyOffice 内部格式后丢失一部分样式信息。我自己在实现“保留 Excel 原始表格样式”时踩过这个坑。默认情况下OnlyOffice 对 xlsx 的解析会做一层内部归一化如果源文件某些样式比较冷门比如自定义数字格式、特殊条件格式规则转换后可能会出现略微差异。而显式带上assemblyFormatAsOrigin: true就是告诉服务端这个文档在排版解析时优先尊重源文件的格式定义。这里要说明一点它不是前端 API 里的常规配置项更多是出现在 Document Server 的转换配置、自定义插件配置或者某些集成方案中。很多人会把它写进前端的document配置里结果是无效的。正确的使用方式要看具体集成场景如果用的是只读预览方案比如把 Office 文件转成 PDF 预览可以在转换请求里带上这个参数如果直接走DocEditor编辑器这个参数一般不需要手动控制。我给的实操建议是在做转换接口调用时手动加上assemblyFormatAsOrigin: true能明显减少“转出来的 PDF 和原文件排版差好多”的抱怨。如果发现加了参数后某些复杂文档依然异常优先排查源文件格式是否官方支持而不是死磕参数。不要每一处都无脑加。遇到有密码保护的文档、带有宏的文件转换逻辑可能会不同这时候先去掉这个参数对比两个结果再判断。3.3 协同编辑验证至少要测这三种情况Once Document Server 跑起来、前端接入完成就要验证协同编辑是不是真的可用。很多人以为两个人同时打开一个文档就算协同其实 OnlyOffice 的协同编辑有严格的前提条件同一个文档 key、同一个 Document Server 实例、网络互通。我应该验证的最小场景有三个场景一两人同时编辑同一单元格。打开同一个文档后A 用户在 B1 单元格输入内容B 用户的界面应该能看到光标位置和实时输入状态。如果 B 看不到任何 A 的操作最可能的问题是两个人加载文档时用了不同的key或者是通过不同 URL 打开导致服务端认为是两个不同文档。场景二增量保存与回调。A 编辑后关闭文档业务系统应该收到callbackUrl的 POST 请求里面带文档状态和临时文件名。这一步很多人会忽略结果就是“编辑完了以为保存了实际上 OnlyOffice 只是把内容存到了自己的临时目录”。回调接口至少要返回{error: 0}的 JSONOnlyOffice 才会认为保存成功。场景三断线重连。把 Document Server 容器重启正在编辑的页面应该能自动重连。如果一直转圈要去看容器日志里是否有 WebSocket 相关的报错尤其是在用了 Nginx 反向代理的情况下WebSocket 的Upgrade头必须正确转发。我这部分就踩过一次前端配置了协同编辑的权限选项但 Document Server 的 JWT 校验未打开于是任何人都能通过伪造参数来改文档。这个问题在开发环境不容易暴露但上线前务必确认 JWT 已开启否则你的文档等于裸奔。开 JWT 的方法是在启动容器时设置环境变量同时在请求的配置里附带生成好的 token。4. 轻量嵌入式方案实测Univer 和 Jspreadsheet 能替你省哪些事4.1 三者的能力边界对比在深入用 OnlyOffice 之后我反而对 Univer 和 Jspreadsheet 的定位更清楚了。它们之间的关系不是替代而是互补。用一个表格来对比会更直观对比项UniverJspreadsheetOnlyOffice Document Server部署形态前端组件可本地打包部署前端组件可本地打包部署独立服务端需要 Docker 或物理机部署核心优势类 Excel 体验公式引擎强Canvas 渲染轻量上手快适合数据录入场景格式兼容度高原生编辑 docx/xlsx/pptx协同编辑支持但需要配合服务端默认不支持实时协同原生支持实时协同打开 Excel 文件部分兼容复杂样式可能丢不擅长复杂 Excel 样式官方主打格式还原度高适合场景需要在线表格且想控制前端体验的产品后台系统的数据表格录入企业办公文档在线预览与协作开发成本中等需要理解 Univer 的渲染机制低套表格组件即可较高要部署和维护 Document Server这个表格不是我随便画的都是实际跑过之后总结的。4.2 Univer 的实际使用体验Univer 给我的第一印象是“长得像 Excel速度很快”。它用 Canvas 画表格滚动和大数据量渲染确实比传统 DOM 表格强。如果你要做一个类似在线报表编辑的工具它的公式、筛选、条件格式、图表这些模块都做得比较完整而且完全开源不受制于商业授权。但它也有明显短板。我拿一个带透视表、条件格式、跨 sheet 引用的 xlsx 文件测试Univer 加载后部分条件格式失效公式结果倒是能正常算。这说明它的 xlsx 解析协议还达不到 100% 兼容 Office 的程度。如果你的目标是“用户上传一个 Excel在上面继续编辑保存后格式不能差太多”Univer 目前还不够稳。比较适合 Univer 的场景是你的系统本身就需要一个“动态表格”比如在线问卷、数据填报、项目管理表数据是业务系统生成的而不是用户上传的真实 Excel。这种场景下用 Univer 做前端表格等于给产品加了一个非常强的交互层。4.3 Jspreadsheet 的适用边界Jspreadsheet 更轻依赖jquery官方文档很简洁。它在表格编辑、行列增删、数据验证方面做得不错适合做后台管理系统里的数据录入组件。我见过很多后台项目用它替代原生的table来录入批量数据配合下拉框、日期选择器开发效率很高。它最大的问题是功能性太偏“网格”而不是“电子表格”。比如跨 sheet 引用、数组公式、图表联动这些在 Excel 里很基础的能力Jspreadsheet 基本没有。如果你的需求只是“填一张表然后提交到后端”选它没错如果你要做复杂财务分析它撑不住。有人可能想用 Jspreadsheet 的“导出 Excel”功能实际导出的文件也就是 CSV 级别的效果样式基本没有。所以这类轻量方案更适合内部数据管理不适合面向最终用户的正式文档导出。4.4 能不能把三者组合起来用我的答案是能但要注意各干各的活。我在一个实际项目里做过这样的组合用户在前端用 Jspreadsheet 快速录入数据点保存后把数据传给后端生成 xlsx 模板文件后端拿到 xlsx 之后再用 OnlyOffice Document Server 渲染成预览界面用户点“在线编辑”就进入 OnlyOffice 编辑模式做精细调整和多人协作。这样既保证了录入效率又拿到了 Office 级别的格式兼容关键是每个工具都只用自己最擅长的部分。如果你想更进一步可以把 Univer 对接到 OnlyOffice 的文档存储层用 Univer 做轻量展示OnlyOffice 做完整编辑。不过这一步的维护成本不低除非业务确实需要否则不建议一上来就这么做。5. 从初步尝试到稳定使用的几个教训写到最后分享几个我自己常用的排查思路比任何配置模板都更耐用。第一个教训不要急着上全家桶。Once 我图省事直接把 OnlyOffice Community Server 也装上了结果它的协作模块依赖邮件服务器、外部存储配置维护成本一下子涨了很多。后来我全部退回到只部署 Document Server业务系统自己控制文档的存储和权限反而简单可靠。OnlyOffice Document Server 本身是一套很完整的文档服务你不要被“全家桶”迷惑能用 API 解决的集成就别碰全家桶。第二个教训日志是最好的老师。不管是 Docker 镜像安装问题还是在线协同编辑异常第一步永远是看容器日志。docker logs会比前端控制台多暴露很多底层信息。有一次我配置 JWT 后始终报 401前端看不出任何问题只有日志里提示Invalid token顺着这个信息才知道是环境变量没生效重启容器后解决。所以排查时别靠猜先看 logs。第三个教训文档缓存是协同编辑里最容易被忽略的坑。Document Server 会根据key缓存文档某个 key 对应的文档内容已经更新但前端没换 key服务端就会一直返回旧版本。这在前端联调时很难发现因为刷新页面也可能拿到缓存。一个稳妥的做法是在文档保存成功后强制生成一个全新的 key而不是随便传一个固定的字符串。这也能避免多个用户操作同名不同内容文件时串数据。最后一点assemblyFormatAsOrigin 这类参数别只当黑盒抄。它的名字已经说明了作用——按原始格式组装本质是让服务端转换时尽量贴着源文件的结构走。理解了这个含义你再遇到 OnlyOffice 打开文档时样式偏移的问题就清楚该往哪个方向排查了。这和缩略词、热搜词没关系纯粹是你看懂参数逻辑之后自然具备的判断力。这三个项目我现在都在用Univer 负责对外展示的炫酷表格界面Jspreadsheet 负责内部快速数据录入OnlyOffice Document Server 负责正式的文档协同。它们各管一段配合下来效果比硬用某一个强得多。如果你的需求就是给网站加个表格没必要上来就部署 OnlyOffice如果你想做真正意义的多人编辑企业文档那 Jspreadsheet 和 Univer 再怎么折腾也代替不了 OnlyOffice 的位置。
OnlyOffice在线协同编辑实践：Docker部署与assemblyFormatAsOrigin参数解析
1. 三个名字背后其实是三种完全不同的“在线编辑”方案先说点实际的。很多人第一次看到“unver、jsspredsheet、onlyoffice”这几个词放在一起会以为它们是同类产品对比。其实不是Univer没错你搜到的 unver 就是它只是经常被缩写或者拼错、Jspreadsheet同样jsspredsheet 是它的常见笔误和 OnlyOffice虽然都做在线编辑但做的事情完全不同。Univer 是一个开源的表格式办公套件定位有点像 Google Sheets 的本地化替代但它不是让你访问一个网站来用而是给你一套组件你可以把它嵌到自己的系统里实现单元格编辑、公式计算、条件格式、筛选、图表甚至协同编辑整个渲染是基于 Canvas 的所以用起来比传统 DOM 表格流畅很多。Jspreadsheet 则是一个更轻量的 JavaScript 数据表格插件依赖 jQuery主打的是快速生成可编辑的数据网格。它更适合做管理后台里的那种“在线录入表格”而不是一个完整的 Office 套件。它的体积小、上手快但功能深度远不如 Univer 或 OnlyOffice。OnlyOffice 是最重的一个它是一整套办公套件包含文本编辑器、电子表格、演示文稿并且带服务端。你部署了 OnlyOffice Document Server 之后通过 API 就能在自己的业务系统里打开 docx、xlsx、pptx实现多人实时协同编辑。它的核心价值在于“兼容 Office 格式”而 Univer 和 Jspreadsheet 更偏“前端交互”。所以你首先要搞清楚自己要解决什么问题是想在自己的网页里做一张可编辑的表格还是想做一个正经的在线文档协同系统这两种需求的选型方向完全不同。我最初接触这三样东西是因为要给客户的内部系统加一个在线预览和编辑 xlsx 的功能。当时我先试了 Jspreadsheet发现它处理大表格性能不错但一碰到 Excel 自带的复杂样式、公式跨表引用就力不从心。然后试了 Univer它在表格内核上做得确实更接近 Excel但依然没法原生打开 xlsx 文件并保留所有元素。最后才回过头认真研究 OnlyOffice 的文档服务。这一篇就把我自己的初步实践过程写清楚尤其是 OnlyOffice 的 Docker 镜像安装、协同编辑接入以及很多人搜过的那个有点奇怪的参数assemblyFormatAsOrigintrue到底是怎么回事。2. 搭建 OnlyOffice 文档服务器Docker 镜像安装的前前后后2.1 为什么第一步就走 Docker 镜像安装OnlyOffice 有两条部署路线一条是装全家桶Community Server Document Server一条是只装 Document Server。全家桶带项目管理、CRM、邮件这些协作功能看起来功能很全但对于只想在自己系统里嵌入在线编辑的开发者来说太重了。我实际测试下来只部署 Document Server 就够了它专门负责文档的保存、转换、协同编辑对外提供 API。而 Document Server 最省事的安装方式就是 Docker 镜像。你不需要在一台空机器上手动装 PostgreSQL、Redis、RabbitMQ、Nginx 这些依赖镜像里全都有。你要做的只是把容器跑起来把数据卷挂出来把端口映射好。如果你是从零开始且没有太多服务器运维经验我强烈建议直接用 Docker。OnlyOffice 官方提供的文档里写的安装步骤也是默认以 Docker 为主的社区里遇到安装问题十有八九也是围绕 Docker 环境讨论。2.2 最简部署命令和参数说明先看一下我最开始用的最简启动命令sudo docker run -i -t -d -p 80:80 --restartalways \ -v /app/onlyoffice/DocumentServer/logs:/var/log/onlyoffice \ -v /app/onlyoffice/DocumentServer/data:/var/www/onlyoffice/Data \ -v /app/onlyoffice/DocumentServer/lib:/var/lib/onlyoffice \ -v /app/onlyoffice/DocumentServer/db:/var/lib/postgresql \ onlyoffice/documentserver:latest解释一下几个关键点-p 80:80是把容器里的 80 端口映射到宿主机 80 端口。如果你的 80 端口已经被 Nginx 占用可以改成-p 8080:80后面访问地址就带端口。--restartalways保证服务器重启后容器自动拉起这个很重要不然后面隔三差五发现服务挂了。数据卷必须挂。/var/log/onlyoffice是日志目录排查安装问题全靠它/var/www/onlyoffice/Data是配置数据/var/lib/postgresql是数据库目录不挂的话容器一删所有文档元数据都没了。启动之后在浏览器访问http://你的服务器IP如果能看到一个“ONLYOFFICE Document Server”的欢迎页说明基本装好了。接下来就可以用/web-apps/apps/api/documents/api.js这个入口来对接前端的 JS API 了。我后来在生产环境里实际用的命令比这个多加了几个参数比如时区、JWT 密钥、内存限制。这里有一个容易忽略的点OnlyOffice Document Server 对系统内存有要求官方建议至少 2GB如果你在低配机器上强行跑文档转换时很容易崩。查看容器日志时如果看到内存相关的报错优先把内存升上去不要先怀疑代码。镜像安装的优点是可以省去手动初始化数据库的步骤缺点恰恰是出了问题不容易看到底层所以日志目录一定要提前规划好后面排查安装问题全靠它。2.3 常见安装问题端口冲突、域名校验、文档转换失败我在搭建过程中和后来帮朋友排查时最常见的安装问题基本集中在下面几类我用表格列一下现象可能原因处理办法容器启动了但页面打不开宿主机 80 端口被其他服务占用换一个宿主端口映射比如-p 8081:80并确认防火墙放行打开欢迎页正常但预览文档一直转圈服务器无法访问自身生成的下载链接检查回调 URL 配置确保前端传的document.url能被 Document Server 访问到这个“自我访问”问题在内网部署时极其常见上传 docx 后显示“未找到文件”容器内部 DNS 无法解析外部下载地址给容器配置 DNS 或直接用外网可访问的 URL不能填localhost能打开文档但保存失败JWT 密钥不一致前端初始化DocEditor时配置的token和 Document Server 环境变量里的JWT_SECRET必须一致转换耗时长或失败服务器内存不足或目标格式不受支持提高内存、排查日志确认格式是否在支持列表内这里面我特别想强调“文档转换失败”这一条。OnlyOffice 在前端展示 docx、xlsx 时并不是直接把原始文件拿来显示而是会先转换排版和内部格式。如果 Document Server 所在服务器访问不到文件 URL转换必然失败。很多人在本地联调时用http://localhost传 URLDocument Server 在容器里当然访问不到宿主机的 localhost。正确做法是在同一局域网内直接用宿主机 IP或者把文件转成 base64 走file字段。还有一类问题修改了 JWT_SECRET 之后旧的容器还是用自己的密钥导致前端一直报鉴权失败。这时候不要只改配置要重启容器并清一下 Redis 缓存。OnlyOffice 的 JWT 机制排查起来很绕建议一开始就统一用一个固定的强密钥前后端、环境变量保持一致别频繁换。3. 在线协同编辑接入从 API 初始化到assemblyFormatAsOrigintrue3.1 前端接入的完整套路OnlyOffice 在线协同编辑不是一个纯前端组件它需要你的业务系统把文档信息告诉 Document Server由 Document Server 负责加载文档、分发给各个在线用户。前端要做的事情其实很集中在页面引入https://你的服务器地址/web-apps/apps/api/documents/api.js。构造一个配置对象包含文档类型、文档 URL、权限、编辑器模式、回调地址等。初始化new DocsAPI.DocEditor(placeholder, config)。一个最小可用的配置大致长这样const docEditor new DocsAPI.DocEditor(docs-container, { document: { fileType: xlsx, key: unique-document-key-001, title: 销售统计表.xlsx, url: http://宿主机IP/example.xlsx, }, documentType: cell, editorConfig: { mode: edit, callbackUrl: http://宿主机IP/callback, user: { id: user-001, name: 张三, }, }, width: 100%, height: 100%, });有几个细节值得注意document.key是一个业务系统自己维护的文档唯一标识。OnlyOffice 用它做缓存判断如果同一个 key 的文档内容变了你需要更新 key否则服务端可能不会重新加载新内容。很多人改了文件但界面上还是旧的多半是 key 没有更新。document.url必须是 Document Server 能访问到的地址。如果你的文件在业务系统内网Document Server 也在同一内网直接填内网 IP 就行如果用公网服务器就要填能被公网访问的 URL。editorConfig.user是当前编辑人的身份。协同编辑时多人同时打开同一文档就是靠这个 user 区分不同用户的头像和光标。callbackUrl是 Document Server 在保存文档时通知你业务系统的地址。如果你想把编辑后的文档存回自己的服务器必须在回调接口里接收数据并做处理否则文档只保存在 OnlyOffice 的临时目录里。3.2assemblyFormatAsOrigintrue到底是干嘛的这个参数在 OnlyOffice 的讨论区里出现频率很高尤其是一些搜索热词里直接和 onlyoffice 放在一起。它最初出现在 Document Server 的内部转换请求接口里作用简单说就是让文档在转换和渲染时尽量以原始格式的规则来处理而不是强制转换成 OnlyOffice 内部格式后丢失一部分样式信息。我自己在实现“保留 Excel 原始表格样式”时踩过这个坑。默认情况下OnlyOffice 对 xlsx 的解析会做一层内部归一化如果源文件某些样式比较冷门比如自定义数字格式、特殊条件格式规则转换后可能会出现略微差异。而显式带上assemblyFormatAsOrigin: true就是告诉服务端这个文档在排版解析时优先尊重源文件的格式定义。这里要说明一点它不是前端 API 里的常规配置项更多是出现在 Document Server 的转换配置、自定义插件配置或者某些集成方案中。很多人会把它写进前端的document配置里结果是无效的。正确的使用方式要看具体集成场景如果用的是只读预览方案比如把 Office 文件转成 PDF 预览可以在转换请求里带上这个参数如果直接走DocEditor编辑器这个参数一般不需要手动控制。我给的实操建议是在做转换接口调用时手动加上assemblyFormatAsOrigin: true能明显减少“转出来的 PDF 和原文件排版差好多”的抱怨。如果发现加了参数后某些复杂文档依然异常优先排查源文件格式是否官方支持而不是死磕参数。不要每一处都无脑加。遇到有密码保护的文档、带有宏的文件转换逻辑可能会不同这时候先去掉这个参数对比两个结果再判断。3.3 协同编辑验证至少要测这三种情况Once Document Server 跑起来、前端接入完成就要验证协同编辑是不是真的可用。很多人以为两个人同时打开一个文档就算协同其实 OnlyOffice 的协同编辑有严格的前提条件同一个文档 key、同一个 Document Server 实例、网络互通。我应该验证的最小场景有三个场景一两人同时编辑同一单元格。打开同一个文档后A 用户在 B1 单元格输入内容B 用户的界面应该能看到光标位置和实时输入状态。如果 B 看不到任何 A 的操作最可能的问题是两个人加载文档时用了不同的key或者是通过不同 URL 打开导致服务端认为是两个不同文档。场景二增量保存与回调。A 编辑后关闭文档业务系统应该收到callbackUrl的 POST 请求里面带文档状态和临时文件名。这一步很多人会忽略结果就是“编辑完了以为保存了实际上 OnlyOffice 只是把内容存到了自己的临时目录”。回调接口至少要返回{error: 0}的 JSONOnlyOffice 才会认为保存成功。场景三断线重连。把 Document Server 容器重启正在编辑的页面应该能自动重连。如果一直转圈要去看容器日志里是否有 WebSocket 相关的报错尤其是在用了 Nginx 反向代理的情况下WebSocket 的Upgrade头必须正确转发。我这部分就踩过一次前端配置了协同编辑的权限选项但 Document Server 的 JWT 校验未打开于是任何人都能通过伪造参数来改文档。这个问题在开发环境不容易暴露但上线前务必确认 JWT 已开启否则你的文档等于裸奔。开 JWT 的方法是在启动容器时设置环境变量同时在请求的配置里附带生成好的 token。4. 轻量嵌入式方案实测Univer 和 Jspreadsheet 能替你省哪些事4.1 三者的能力边界对比在深入用 OnlyOffice 之后我反而对 Univer 和 Jspreadsheet 的定位更清楚了。它们之间的关系不是替代而是互补。用一个表格来对比会更直观对比项UniverJspreadsheetOnlyOffice Document Server部署形态前端组件可本地打包部署前端组件可本地打包部署独立服务端需要 Docker 或物理机部署核心优势类 Excel 体验公式引擎强Canvas 渲染轻量上手快适合数据录入场景格式兼容度高原生编辑 docx/xlsx/pptx协同编辑支持但需要配合服务端默认不支持实时协同原生支持实时协同打开 Excel 文件部分兼容复杂样式可能丢不擅长复杂 Excel 样式官方主打格式还原度高适合场景需要在线表格且想控制前端体验的产品后台系统的数据表格录入企业办公文档在线预览与协作开发成本中等需要理解 Univer 的渲染机制低套表格组件即可较高要部署和维护 Document Server这个表格不是我随便画的都是实际跑过之后总结的。4.2 Univer 的实际使用体验Univer 给我的第一印象是“长得像 Excel速度很快”。它用 Canvas 画表格滚动和大数据量渲染确实比传统 DOM 表格强。如果你要做一个类似在线报表编辑的工具它的公式、筛选、条件格式、图表这些模块都做得比较完整而且完全开源不受制于商业授权。但它也有明显短板。我拿一个带透视表、条件格式、跨 sheet 引用的 xlsx 文件测试Univer 加载后部分条件格式失效公式结果倒是能正常算。这说明它的 xlsx 解析协议还达不到 100% 兼容 Office 的程度。如果你的目标是“用户上传一个 Excel在上面继续编辑保存后格式不能差太多”Univer 目前还不够稳。比较适合 Univer 的场景是你的系统本身就需要一个“动态表格”比如在线问卷、数据填报、项目管理表数据是业务系统生成的而不是用户上传的真实 Excel。这种场景下用 Univer 做前端表格等于给产品加了一个非常强的交互层。4.3 Jspreadsheet 的适用边界Jspreadsheet 更轻依赖jquery官方文档很简洁。它在表格编辑、行列增删、数据验证方面做得不错适合做后台管理系统里的数据录入组件。我见过很多后台项目用它替代原生的table来录入批量数据配合下拉框、日期选择器开发效率很高。它最大的问题是功能性太偏“网格”而不是“电子表格”。比如跨 sheet 引用、数组公式、图表联动这些在 Excel 里很基础的能力Jspreadsheet 基本没有。如果你的需求只是“填一张表然后提交到后端”选它没错如果你要做复杂财务分析它撑不住。有人可能想用 Jspreadsheet 的“导出 Excel”功能实际导出的文件也就是 CSV 级别的效果样式基本没有。所以这类轻量方案更适合内部数据管理不适合面向最终用户的正式文档导出。4.4 能不能把三者组合起来用我的答案是能但要注意各干各的活。我在一个实际项目里做过这样的组合用户在前端用 Jspreadsheet 快速录入数据点保存后把数据传给后端生成 xlsx 模板文件后端拿到 xlsx 之后再用 OnlyOffice Document Server 渲染成预览界面用户点“在线编辑”就进入 OnlyOffice 编辑模式做精细调整和多人协作。这样既保证了录入效率又拿到了 Office 级别的格式兼容关键是每个工具都只用自己最擅长的部分。如果你想更进一步可以把 Univer 对接到 OnlyOffice 的文档存储层用 Univer 做轻量展示OnlyOffice 做完整编辑。不过这一步的维护成本不低除非业务确实需要否则不建议一上来就这么做。5. 从初步尝试到稳定使用的几个教训写到最后分享几个我自己常用的排查思路比任何配置模板都更耐用。第一个教训不要急着上全家桶。Once 我图省事直接把 OnlyOffice Community Server 也装上了结果它的协作模块依赖邮件服务器、外部存储配置维护成本一下子涨了很多。后来我全部退回到只部署 Document Server业务系统自己控制文档的存储和权限反而简单可靠。OnlyOffice Document Server 本身是一套很完整的文档服务你不要被“全家桶”迷惑能用 API 解决的集成就别碰全家桶。第二个教训日志是最好的老师。不管是 Docker 镜像安装问题还是在线协同编辑异常第一步永远是看容器日志。docker logs会比前端控制台多暴露很多底层信息。有一次我配置 JWT 后始终报 401前端看不出任何问题只有日志里提示Invalid token顺着这个信息才知道是环境变量没生效重启容器后解决。所以排查时别靠猜先看 logs。第三个教训文档缓存是协同编辑里最容易被忽略的坑。Document Server 会根据key缓存文档某个 key 对应的文档内容已经更新但前端没换 key服务端就会一直返回旧版本。这在前端联调时很难发现因为刷新页面也可能拿到缓存。一个稳妥的做法是在文档保存成功后强制生成一个全新的 key而不是随便传一个固定的字符串。这也能避免多个用户操作同名不同内容文件时串数据。最后一点assemblyFormatAsOrigin 这类参数别只当黑盒抄。它的名字已经说明了作用——按原始格式组装本质是让服务端转换时尽量贴着源文件的结构走。理解了这个含义你再遇到 OnlyOffice 打开文档时样式偏移的问题就清楚该往哪个方向排查了。这和缩略词、热搜词没关系纯粹是你看懂参数逻辑之后自然具备的判断力。这三个项目我现在都在用Univer 负责对外展示的炫酷表格界面Jspreadsheet 负责内部快速数据录入OnlyOffice Document Server 负责正式的文档协同。它们各管一段配合下来效果比硬用某一个强得多。如果你的需求就是给网站加个表格没必要上来就部署 OnlyOffice如果你想做真正意义的多人编辑企业文档那 Jspreadsheet 和 Univer 再怎么折腾也代替不了 OnlyOffice 的位置。
