ARTICLE · 1351176

SpringBoot+OnlyOffice:在线 Word 编辑、转化、保存,一套方案搞定

发布时间：2026-11-13 16:08:55 最近访问：2026-11-13 16:08:55

做过文档管理系统的朋友应该都遇到过这个需求：用户上传一个 Word 文件，想直接在浏览器里修改，改完还能保存回服务器，最好再支持 Word 转 PDF。

如果让后端自己解析 DOCX、处理编辑操作、再重新生成文件，这条路很快就会走复杂。尤其是表格、页眉页脚、图片、分页这些东西，稍微处理不好，文档格式就乱了。

我的思路是：文档编辑交给 OnlyOffice，业务管理交给 SpringBoot，文件存储由自己的服务负责。这几个边界划清楚，后面维护起来会省心不少。

一、先把整体流程跑通

整体架构并不复杂。

前端通过 OnlyOffice 的 JavaScript API 加载 Word 编辑器。
SpringBoot 负责生成编辑器配置，并提供文档下载地址。
OnlyOffice Document Server 负责真正的文档编辑和格式转换。
用户点击保存后，OnlyOffice 将编辑结果通过回调通知 SpringBoot。
SpringBoot 下载最新文件，再保存到文件服务器或对象存储。

这里有个容易搞错的地方：用户在编辑器里按下保存，不代表你的 SpringBoot 服务已经拿到了最新文件。文档保存通常涉及 OnlyOffice 的回调机制，后端必须正确处理回调状态。

部署时，SpringBoot 和 OnlyOffice Document Server 需要能够通过网络互相访问。如果启用了 JWT，还要保证两边的密钥配置一致。

二、SpringBoot 生成编辑器配置

假设数据库里保存了文档 ID、文件名和存储路径。用户打开文档时，后端根据文档 ID 查询元数据，生成编辑器需要的配置。

下面以 SpringBoot、Java 为例，演示核心配置。documentUrl 是 OnlyOffice 能够访问的文件下载地址，不能随便填一个浏览器本地地址。

public Map<String, Object> buildEditorConfig(
        String docId, String documentUrl, String userId) {

    Map<String, Object> document = new HashMap<>();
    document.put("fileType", "docx");
    document.put("key", docId + "-" + System.currentTimeMillis());
    document.put("title", "项目方案.docx");
    document.put("url", documentUrl);

    Map<String, Object> permissions = new HashMap<>();
    permissions.put("edit", true);
    permissions.put("download", true);

    Map<String, Object> config = new HashMap<>();
    config.put("document", document);
    config.put("documentType", "word");
    config.put("editorConfig", Map.of(
"mode", "edit",
"user", Map.of("id", userId, "name", "文档编辑者")
    ));

return config;
}

这段代码展示的是配置结构，生产环境还需要补齐权限校验、JWT 签名以及文件元数据查询。

尤其是 document.key，不要一直使用固定值。OnlyOffice 会利用它识别文档版本和缓存，同一份文档在内容更新后，应使用能够区分版本的 key，否则可能遇到编辑器仍然加载旧内容的问题。

另外，示例中的 permissions 只是展示权限数据的写法，实际使用时要把它放进 OnlyOffice 对应的配置节点，并根据业务角色控制编辑权限。

三、保存才是真正需要注意的地方

OnlyOffice 编辑器会向后端指定的 callbackUrl 发送保存状态。后端收到回调后，需要根据状态判断是否应该下载最新文件。

常见的状态中，2 表示文档已准备好保存，6 表示强制保存完成。具体处理逻辑应结合部署版本和实际回调行为确认。

@PostMapping("/onlyoffice/callback/{docId}")
public Map<String, Object> saveCallback(
        @PathVariable String docId,
        @RequestBody Map<String, Object> body) {

    int status = ((Number) body.get("status")).intValue();

if (status == 2 || status == 6) {
        String downloadUrl = (String) body.get("url");

        // 下载最新 DOCX 文件，校验后写入存储
        documentStorageService.saveLatest(docId, downloadUrl);
    }

return Map.of("error", 0);
}