使用onlyoffice实现文件预览编辑 + Docker一键部署流程

ONLYOFFICE 是一款功能完备的在线办公套件，提供 Word、Excel、PPT 等常用办公工具，用户仅需通过浏览器即可访问所有 Office 功能。
https://api.onlyoffice.com/zh-CN/docs/docs-api/get-started/frontend-frameworks/vue/

在 Vue3 项目中集成 OnlyOffice Document Server 需完成服务部署、前后端交互、组件封装三大核心步骤，最终实现文件的在线编辑 / 预览功能。

ONLYOFFICE 前端嵌入依赖 后端服务支撑 （前端无法单独运行）

但无需自己开发复杂后端个人测试使用可以使用docker进行流程化一键部署

项目中后端提供接口支持即可

OnlyOffice 与前端的交互流程：

前端从业务后端获取文件访问链接、文档密钥和配置参数
后端与 Document Server 交互，生成编辑会话和 iframe 嵌入地址前端通过 iframe 嵌入编辑页面加载文件
Document Server 实时回调业务后端处理文件保存

一、Docker 部署 ONLYOFFICE 服务
第一步：配置环境以适应docker

启用适用于 Linux 的 Windows 子系统

检查系统虚拟化是否开启

以管理员身份运行命令窗口

WSL 是 Windows Subsystem for Linux 的缩写，中文名为适用于 Linux 的 Windows 子系统，是微软为 Windows 10/11 系统推出的一项功能，它允许用户在 Windows 系统中原生运行 Linux 环境（包括 Linux 命令行工具、应用程序、服务等），而无需安装虚拟机或双系统。

执行命令：

wsl --install

wsl --version

安装过程中需设置用户名和密码自定义即可

第二步：安装 Docker（前置工具）

下载 Docker Desktop（Windows/macOS）或 Docker Engine（Linux）

官方下载地址

验证安装：打开终端（Windows 用 PowerShell，macOS/Linux 用终端），输入以下命令，显示版本则安装成功

javascript 复制代码

docker --version

第三步：Docker 部署 ONLYOFFICE Docs 服务

配置镜像拉取地址
在powershell 中执行下面命令进行镜像拉取

javascript 复制代码

docker pull onlyoffice/documentserver:latest

启动容器（首次运行需设置端口）

在 powershell 中执行下方三条命令注意 windows 系统中去掉sudo 直接执行 sudo后面的命令即可

访问时需将 localhost 替换为本机 IP

二、Vue 项目集成

安装依赖：

javascript 复制代码

npm install --save @onlyoffice/document-editor-vue

这个错误提示（"文档安全令牌格式不正确"）是 OnlyOffice Document Server 的令牌验证机制触发的，问题根源是前端未正确传递合法的 JWT 令牌，或服务端的令牌验证未关闭

可以关闭前端的令牌校验

javascript 复制代码

//进入容器
docker exec -it **id** bash
//编辑容器配置文件
nano /etc/onlyoffice/documentserver/local.json
//重启容器服务
supervisorctl restart all

在nano编辑器中保存修改的步骤如下：

按下 Ctrl + O（用于保存文件）；
此时会在底部提示 "File Name to Write: /etc/onlyoffice/documentserver/local.json"，直接按Enter键确认保存路径；
保存完成后，按下 Ctrl + X 退出nano编辑器。

三、配置说明

核心配置项分为 基础配置、文档配置、编辑器配置、界面自定义配置 等类别，以下是常用且关键的配置项

1、核心基础配置

这些是初始化 OnlyOffice 编辑器的必填 / 基础参数：

2、文档配置（document 字段）

用于定义要打开的文档信息：

3、编辑器配置（editorConfig 字段）

控制编辑器的功能、语言、用户信息等：

4、界面自定义配置（editorConfig.customization 字段）

用于调整编辑器的界面显示：

5、事件配置（Vue3 组件中绑定）

在 Vue3 组件中可以监听 OnlyOffice 的事件，实现业务逻辑：

javascript 复制代码

<template>
  <div id="onlyoffice-container" style="width: 100%; height: 800px;"></div>
</template>

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  const initEditor = () => {
    new window.DocsAPI.DocEditor("onlyoffice-container", {
      // 基础配置
      documentServerUrl: "http://172.31.0.1:9000/",
      documentType: "word",
      type: "desktop",
      width: "100%",
      height: "800px",
      // 文档配置
      document: {
        url: "https://static.onlyoffice.com/assets/docs/samples/demo.docx"
        fileType: "docx",
        key: "doc-key-20251216",
        title: "测试文档.docx",
        permissions: {
          edit: true,
          download: false
        }
      },
      // 编辑器配置
      editorConfig: {
        lang: "zh-CN",
        mode: "edit",
        user: { id: "1", name: "Vue用户" },
        callbackUrl: "http://你的后端/api/onlyoffice/callback",
        customization: {
          forcesave: true,
          toolbar: { hide: ["print"] }
        }
      },
      // 事件监听
      events: {
        onDocumentReady: () => console.log("文档加载完成"),
        onError: (err) => console.error("编辑器错误:", err)
      }
    });
  };

  // 加载 OnlyOffice API 后初始化
  const script = document.createElement("script");
  script.src = "http://localhost:9000/web-apps/apps/api/documents/api.js";
  script.onload = initEditor;
  document.body.appendChild(script);
});
</script>