用OnlyOffice在网页里预览Word、Excel、PPT、PDF听起来像是一件很常规的事但真要把这四类文件统一跑通并且做到只需要双击一个index.html就能看到预览效果我前前后后折腾了两个晚上。最后成型的demo不复杂前端就是一个HTML页面服务端是一个用Docker跑起来的OnlyOffice Document Server把两样东西接到一起浏览器里就能像打开本地Office一样阅读各种文档了。这篇文章就是这份demo的完整复盘。适合正在给OA、网盘、知识库、工单系统做在线预览功能的人也适合刚接触OnlyOffice、想先花半小时跑通概念的同学。我会把选型理由、运行原理、部署命令、前端接入代码、白屏排错、不同格式的实测差异全部写出来最后再聊聊从“预览”延伸到“在线编辑”“批注读取”“多人协同”的进阶思路。1. 为什么绕了一大圈最后选了OnlyOffice做预览1.1 我提前试过的那几条路问题都在哪儿最早接到这个需求时我的第一反应其实是“直接iframe套一下不就行了”结果被现实教育得很惨。对于PDF浏览器原生就能显示不用做任何开发但Word、Excel、PPT这些文件扔给浏览器它只会变成一个下载按钮想直接在页面上阅读根本做不到。然后我试了微软的Office Online Viewer就是那种把文件地址拼到一个官方URL后面、自动在网页里打开预览的方式。单看效果确实不错样式还原度很高但它有一个致命前提文件地址必须是公网可访问的URL。我做的是内网文档系统文件都在公司服务器上外网根本访问不到。而且它属于第三方在线服务传文档过去涉及数据安全问题这条线直接被否了。接下来考虑过WPS的WebOffice因为是国产软件对国内场景适配得挺好界面交互也顺手。但问题在于它的接入需要商务洽谈、签合同、拿授权技术验证还没做完流程先卡住了。对于只想快速出一个demo验证效果的人来说这个门槛高得有点不划算。1.2 OnlyOffice的社区版、Docker化部署正好卡在我的需求点上OnlyOffice打动我的点有三个。第一它开源社区版可以免费商用对一个内部工具来说很友好。第二它提供Docker镜像一条命令就能启动一套完整的文档解析服务不需要像LibreOffice那样自己去拼转换服务。第三它的前端嵌入API做得非常薄一个DocsAPI.DocEditor调用就能把编辑器骨架拉起来Word、Excel、PPT、PDF统统走同一套接入逻辑。最后我确定的demo最小闭环是这样一个跑在Docker里的Document Server负责“看得懂”文档一个写死的index.html负责提供“能双击打开”的入口再加上一个放着示例文件的静态文件服务三者连通之后页面就能预览这四类文件了。整套东西没有数据库也不需要写后端接口属于最朴素的能跑版本。2. 一套能预览的链路前后端各自身上的分工是什么2.1 别把“Document Server”和“编辑器文档”搞混很多第一次接触OnlyOffice的人会有一个误解以为index.html里引用的API脚本就是编辑器本身。实际不是。api.js只是前端接线的“遥控器”真正干活的是Document Server这个服务端进程。当你调用new DocsAPI.DocEditor(placeholder, config)时你的页面会把一份config配置交给服务端。服务端拿到这份配置后会先去读取config里的文档地址也就是document.url把原始的docx、xlsx、pptx、pdf文件拉到自己这边然后解析成适合Web渲染的结构再回传给前端页面显示。整个过程可以理解成“你把文件地址告诉服务端服务端负责把文件翻译成浏览器能看懂的格式”。这也是为什么demo里光有一个index.html是不够的——你还得有一个能跑起来的服务端以及一个存文件的静态服务。三者之间的关系大致是这样浏览器双击打开index.html │ │ 1. 从Document Server加载 api.js │ 2. 提交 config内含文档URL ▼ OnlyOffice Document Server地址http://localhost:8080 │ │ 请求 config.document.url ▼ 静态文件服务地址http://localhost:9000/sample.docx这个角色划分非常重要后面的很多排错其实都是在排查这三条链路里哪一条断了。2.2 文档地址要满足“两端可达”用本地文件路径直接预览是不行的因为Document Server在Docker容器里它看不到你电脑的C:\盘路径。config里填的URL必须是一个它通过HTTP能访问到的地址。开发环境最简单的方式就是把示例文件和index.html放到同一个静态服务里然后用http://localhost:9000/sample.docx这样的地址来引用。上传到公司的对象存储或者图床也可以原则只有一个前端浏览器和服务端容器都能访问到这个URL。3. 花三分钟把Document Server用Docker部署起来3.1 Docker run命令和目录规划部署Document Server这一步没什么悬念官方提供了标准镜像命令也基本固定。我习惯先把宿主机上的日志、数据、依赖三个目录建好方便以后升级和排查mkdir -p /opt/onlyoffice/logs mkdir -p /opt/onlyoffice/data mkdir -p /opt/onlyoffice/lib然后启动容器docker run -d -p 8080:80 \ --name onlyoffice-docserver \ --restartalways \ -v /opt/onlyoffice/logs:/var/log/onlyoffice \ -v /opt/onlyoffice/data:/var/www/onlyoffice/Data \ -v /opt/onlyoffice/lib:/var/lib/onlyoffice \ onlyoffice/documentserver:latest端口映射我选了8080因为80在日常开发环境里经常被占用。如果你公司内部有统一的域名和反向代理也可以把80端口让给OnlyOffice后面再通过nginx转发。3.2 健康检查、日志验证、许可证问题一次说清容器启动后不要急着写前端先确认服务真的起来了curl http://localhost:8080/healthcheck如果返回true说明Document Server的核心进程正常。然后看日志docker logs -f onlyoffice-docserver第一次启动时会出现很多初始化信息比如数据库初始化、缓存构建、字体生成之类耐心等一两分钟再检查。这里要特别提醒一件事默认启动的是社区版功能上对内部预览和轻量编辑足够但如果你准备生产商用需要去官方网站申请商业授权。授权文件的挂载方式是-v /path/to/license.lic:/var/www/onlyoffice/Data/license.lic重新启动容器后自动生效不需要改代码。千万不要在生产环境白嫖社区版跑大规模业务后面业务量大了文档响应慢你会非常被动。3.3 示例文件从哪里来起一个极简静态文件服务接着把示例文件准备好。任意目录下放几个文件然后把这个目录变成HTTP静态服务。用Docker跑最省事docker run -d -p 9000:80 \ --name demo-static \ -v $(pwd):/usr/share/nginx/html:ro \ nginx:alpine如果不想启动Docker也可以直接用Pythoncd /your/demo-files python3 -m http.server 9000这样访问http://localhost:9000/sample.docx就能直接拿到文件了。下一步写index.html时config里的document.url就填这个地址。4. index.html核心代码接入预览其实只有几步4.1 先看完整代码再拆字段这是整个demo最核心的部分。我把文件选择器、预览初始化、格式切换全塞进了一个页面这样既能展示Word、Excel、PPT、PDF四种类型又保持着“双击即可看效果”的姿势!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleOnlyOffice 文档预览 Demo/title style body { margin: 0; font-family: Microsoft YaHei, Arial, sans-serif; } #toolbar { background: #f5f5f5; padding: 10px 16px; border-bottom: 1px solid #ddd; display: flex; align-items: center; gap: 10px; } #toolbar select, #toolbar button { padding: 6px 12px; font-size: 14px; } #placeholder { width: 100%; height: calc(100vh - 54px); } /style /head body div idtoolbar select idfileSelector option valuewordWord 示例/option option valueexcelExcel 示例/option option valuepptPPT 示例/option option valuepdfPDF 示例/option /select button idpreviewBtn预览/button /div div idplaceholder/div script srchttp://localhost:8080/web-apps/apps/api/documents/api.js/script script const sampleFiles { word: { documentType: word, fileType: docx, title: 示例文档.docx, url: http://localhost:9000/sample.docx }, excel: { documentType: cell, fileType: xlsx, title: 示例表格.xlsx, url: http://localhost:9000/sample.xlsx }, ppt: { documentType: slide, fileType: pptx, title: 示例演示文稿.pptx, url: http://localhost:9000/sample.pptx }, pdf: { documentType: pdf, fileType: pdf, title: 示例文档.pdf, url: http://localhost:9000/sample.pdf } }; let docEditorInstance null; function preview() { const key document.getElementById(fileSelector).value; const file sampleFiles[key]; const config { document: { fileType: file.fileType, key: key - Date.now(), title: file.title, url: file.url }, documentType: file.documentType, editorConfig: { mode: view, lang: zh-CN, customization: { autosave: false, chat: false, comments: false, help: false } }, height: 100%, width: 100% }; // 切换文件时先销毁上一个实例避免重复初始化 if (docEditorInstance) { docEditorInstance.destroy(); } docEditorInstance new DocsAPI.DocEditor(placeholder, config); } document.getElementById(previewBtn).addEventListener(click, preview); // 页面加载后默认预览 Word preview(); /script /body /html这段代码没有用到任何框架纯原生JS直接保存为index.html就能当demo的入口页。4.2 config里每个字段到底是干什么的接入OnlyOffice时最怕的就是config配错因为它的字段是一套嵌套结构。我整理了一张对应表方便你对照自己的场景改配置字段作用示例值注意事项document.url需要预览的文档真实HTTP地址http://localhost:9000/sample.docx前端和Document Server都要能访问document.fileType文档的格式名docx/xlsx/pptx/pdf大小写不敏感但必须和URL实际文件一致document.key文档的唯一缓存IDword-1700000000保持不同文档不同key相同key会重复使用缓存document.title编辑器顶部显示的文件名示例文档.docx可以带扩展名documentType决定用哪套编辑器类型word/cell/slide/pdf弄错会出现“白屏”或“格式不支持”editorConfig.mode打开后是只读还是可编辑view/edit预览用view编辑再切editeditorConfig.lang界面语言zh-CN不填默认英文height/width编辑器占位尺寸100%/100%支持百分比和像素值最容易被忽视的是documentType和fileType。前者告诉OnlyOffice用编辑器哪个模块后者告诉它解析时按什么格式处理。如果你拿一个PPT文件却把documentType填成了word结果往往不是报错而是页面空白或者样式乱掉。4.3 切换文件时的实例销毁细节第一次写完demo时我遇到的坑在切换文件先看Word没问题切到Excel后页面完全没反应黑屏转圈。原因不是配置而是我在同一个div占位符上连续执行了多次new DocsAPI.DocEditor前一个编辑器实例还占着DOM后面的初始化被它挡住了。解决办法就是文档里明确写的——每次切换前调用一下旧实例的destroy()方法。上面代码里我先用docEditorInstance存住了当前的实例再初始化新文件前销毁旧实例这个顺序不能反先销毁再创建。如果你改成“先创建新的再销毁旧的”新实例会直接覆盖占位符内容旧实例又在异步加载文档很容易出现抢占和错乱。5. 从白屏到能预览本地file协议和跨域问题的完整排查复盘5.1 现象双击index.html以后页面干干净净什么都没有这大概是demo从“写完”到“真正能打开”之间最磨人的一段。我当时把index.html放在本地目录里双击后用file:///C:/demo/index.html打开F12控制台里只有一行红色错误加载api.js失败或者加载后被CORS策略拦了。一开始我以为是地址写错反复核对http://localhost:8080没有问题。后来才反应过来你的页面是通过file://协议打开的浏览器标签页Document Server作为http://localhost:8080上的服务两者用的是不同协议、不同来源浏览器默认不会让你的页面跨协议去拉取JS脚本。5.2 先看脚本加载再看文档请求排查这种问题我建议按两条线走。第一条线打开F12的Network面板刷新页面看api.js的请求状态。如果这个请求是红色blocked或者状态码显示CORS相关错误就说明前端页面和Document Server之间的来源不匹配。最简单的处理方式不是去改服务器CORS配置而是别用file://协议。把index.html放到任意HTTP静态服务里比如我前面起的python3 -m http.server用http://localhost访问页面脚本跨域问题基本就消失了。第二条线确认Document Server能不能“回访”文档URL。因为config里填的http://localhost:9000/sample.docx是前端浏览器能访问的但真正去下载这个文件的不是你的浏览器而是Document Server容器。如果容器里访问不到localhost:9000编辑器就会一直带loading图标最后提示“无法下载文档”。我在本机遇到过一种很典型的情况静态服务和Document Server用的是同一个宿主机的“localhost”这个没问题。但你把demo部署到服务器上、用IP访问页面时会下意识把文档URL填成http://127.0.0.1:9000/sample.docx然后容器就会觉得自己访问的就是自己结果找不到。这种时候要改成宿主机的局域网IP例如http://192.168.1.100:9000/sample.docx。5.3 本机实测最顺的一种打开姿势经过反复折腾我发现“双击index.html”在大部分现代浏览器里确实能直接看效果但这依赖你本机没有任何代理插件、而且浏览器没有收紧file协议跨源限制。如果你想让自己省点心更推荐用一条Python命令把demo目录变成HTTP服务再打开cd /path/to/demo python3 -m http.server 8081然后访问http://localhost:8081/index.html。页面本身跑在HTTP环境里和http://localhost:8080的Document Server属于同源局域网下的跨端口请求浏览器的限制会宽松很多。如果线上发布那就更简单了把index.html扔给任意nginx静态站点托管Document Server用域名或公网地址文档地址用对象存储的URL三个节点都通过公网访问跨域问题基本不存在。5.4 两张排错清单建议直接收藏我把这次踩坑的经验浓缩成两张清单。第一张是“页面打开但是白屏”的检查顺序检查http://localhost:8080/web-apps/apps/api/documents/api.js能否直接在浏览器打开检查curl http://localhost:8080/healthcheck是否返回true检查http://localhost:9000/sample.docx能否直接下载在Document Server容器里执行curl确认它也能访问http://localhost:9000/sample.docx确认documentType和fileType是否匹配第二张是“部分文件能预览、部分文件不行”的检查顺序确认文件本身不是损坏的先用Office或WPS打开验证确认文件名后缀和真实格式一致不要把改了后缀的假docx传上去加大文件或高并发测试时看Document Server所在服务器的内存是否够用6. Word、Excel、PPT、PDF四种格式实测各自的表现和坑6.1 Word版式还原度最好但要注意字体缺失实测下来DOCX在OnlyOffice里的还原度是最高的分页、标题层级、页眉页脚、表格边框、批注标记都能正常显示。对中文用户来说最现实的问题是字体如果Document Server容器里没有安装系统中文字体预览时就会出现字体替换比如宋体被换成默认的sans-serif行距和字号看着会有一两像素偏差。解决方式是在容器里安装中文字体包。以Ubuntu容器为例执行apt-get install -y fonts-wqy-zenhei fonts-wqy-microhei装完重启容器再预览。如果你要展示的文档用了公司定制字体还得把字体文件单独放到容器的/usr/share/fonts目录里刷新字体缓存。6.2 Excel公式和多Sheet是真能用的用OnlyOffice预览Excel是我个人认为比PDF还要舒服的地方。多Sheet切换、冻结行列、数据筛选器、条件格式这些在页面上都能操作公式也会在打开时重新计算。这意味着你甚至可以把一个带交互的Excel报表直接嵌到网页里用户不用下载到本地就能看各个分Sheet的数据。但有一点要注意文件如果带有很重的宏VBAOnlyOffice目前不会执行这些宏。对预览场景这可能反而是个优点——安全。如果你预期用户会用到宏那这个方案撑不住只能回到桌面Office。6.3 PPT静态渲染别期待动画播放PPTX的预览让我刚开始有点不适应——动画和切换效果不会被播放它更接近“按幻灯片的排列方式静态展示每一页”。这其实是好事因为商业汇报场景里用户主要看内容结构而不是炫酷动画。和Word一样字体缺失会明显影响幻灯片的视觉效果同样是那几个中文字体包装完就能解决。另外如果PPT里嵌入了视频/音频文件预览时可能显示不出来需要确认是不是因为容器缺少对应的解码组件。正式的部署建议是给Document Server服务器安装完整的多媒体解码库否则PPT里的视频那一页会黑屏。6.4 PDF当成编辑器里的特殊“文档类型”处理PDF在OnlyOffice里的处理逻辑和其它三类不太一样它的documentType是pdf而不是word/cell/slide。我见过不少人把PDF的documentType配成word结果打开后连页面都不渲染。只要把documentType和fileType都填成PDF基本就能正常显示。PDF预览本身也支持查看注释、签名字段、表单内容打开速度比Office文档快不少因为不需要走繁重的Office解析链路。如果你的业务只需要看PDF文件其实用浏览器原生的iframe就足够了如果你希望用户能在网页端备注、填写表单才值得走OnlyOffice。6.5 四种格式的配置对照表文件类型documentTypefileType常见表现典型坑Wordworddocx/doc版式还原度高中文字体缺失、旧版.doc兼容偶尔错位Excelcellxlsx/xlsSheet切换顺畅、公式可算带宏文件不执行PPTslidepptx/ppt按页静态展示动画/视频不可播PDFpdfpdf打开稳定、速度快documentType配错就直接不渲染7. 预览之外还能怎么玩编辑权限、批注读取和协同编辑7.1 一键从预览切到编辑预览只是绕开了“下载后打开”的那道坎OnlyOffice真正的杀手锏是它能把同一个页面变成在线编辑器。只需要把editorConfig.mode从view改成edit页面里就会多出完整的编辑工具栏用户可以当场改文字、调整表格公式、加批注。但要注意编辑模式会触发保存机制你需要额外配置editorConfig.callbackUrl。当用户在网页里保存文档时Document Server会把这个文档发给回调URL。demo阶段可以不配点保存会发生什么由服务端容忍处理但做正式系统时回调URL必须指向你自己的后端接口否则文档只能临时在内存里改刷新页面就丢了。7.2 批注到底存在哪里怎么取出来网上关于“OnlyOffice批注怎么取”的提问非常多我也被这个问题卡过一下。批注并不是一个独立的API接口直接返回给你而是随着文档一起存在文件内容里。当用户保存文档后你的回调URL会收到一个POST请求里面有一个指向新文档的URL你从那个URL把文档下载回来后解析即可。以Word为例批注保存在docx压缩包里的word/comments.xmlExcel的批注则放在xlsx里的comments相关SheetPPT的批注逻辑也类似。你想在后端统一管理批注就得自己解析这些XML结构。没有“一条API直接列出所有批注”的说法绕过文件层面去取数据基本都会被卡住。7.3 多人协同并不是零成本换配置最后提一下“实时协同编辑”。当多个浏览器同时打开同一份文档时OnlyOffice的Document Server确实具备协同能力同一个key对应同一份文档几台设备同时在线编辑都能看到对方的改动。docker镜像里已经包含了消息推送、Redis这些协同依赖不需要你再单独部署一套。但在真实系统里你还得自己处理文档权限、并发加锁、历史版本保存这些逻辑尤其是“谁在这个文档上编辑谁只能看”的权限控制需要在config里给每个用户分配editorConfig.user信息。把这些都做完才算真正把一个可靠的在线协作文档系统搭起来。到了这一步原先那个“双击就能预览”的demo就完成了它最重要的使命帮你确认了OnlyOffice这条技术路径是走得通的后面再往里填业务能力都不算难。
