OnlyOffice Docs：Next.js中DocumentEditor无法保存修改问题

问题背景 #

Django后端生成OnlyOffice配置返回给Next.js 14应用，编辑器能正常加载并编辑PDF，保存时编辑器提示成功，但刷新页面后修改全部丢失。但将相同配置硬编码到静态HTML中时，保存功能完全正常。

后端返回的配置（已脱敏） #

{
    "document": {
        "fileType": "pdf",
        "key": "xxxxx",
        "title": "Invoice #5046",
        "url": "https://xxxxx",
        "permissions": {
            "edit": true,
            "download": true,
            "comment": true,
            "review": true,
            "chat": false,
            "protect": false
        }
    },
    "editorConfig": {
        "callbackUrl": "https://xxxxx/",
        "mode": "edit",
        "user": {
            "id": "xxxxx",
            "name": "Mustafa Alhasanat"
        }
    },
    "height": "100%",
    "width": "100%",
    "token": "xxxxx"
}

前端核心代码 #

/* eslint-disable @typescript-eslint/no-unused-vars */
/* eslint-disable @typescript-eslint/no-explicit-any */
"use client";

import React from "react";
import { OnlyOfficeConfig } from "only-office";
import { DocumentEditor } from "@onlyoffice/document-editor-react";

function onDocumentReady(event: any) {
    console.log("Document is loaded");
}

function onLoadComponentError(errorCode: any, errorDescription: any) {
    switch (errorCode) {
        case -1: // Unknown error loading component
            console.log(errorDescription);
            break;

        case -2: // Error load DocsAPI from http://documentserver/
            console.log(errorDescription);
            break;

        case -3: // DocsAPI is not defined
            console.log(errorDescription);
            break;
    }
}

export const OnlyOfficeComponent = React.memo(({ config }: { config: OnlyOfficeConfig }) => {
    return (
        <div className="w-full h-full">
            <DocumentEditor
                id="docxEditor"
                documentServerUrl="https://MY_SERVER_URL/"
                config={config}
                events_onDocumentReady={onDocumentReady}
                onLoadComponentError={onLoadComponentError}
            />
        </div>
    );
});

排查与解决步骤 #

1. 锁定document.key的稳定性 #

OnlyOffice通过key识别文件唯一标识，如果动态请求时Django每次返回不同的key，编辑器会认为是新文件，修改不会同步到原文件。

• 解决：基于文件内容哈希、文件ID生成固定key，确保同一文件每次加载返回相同的key，禁止用随机值或请求ID生成。

2. 检查callbackUrl后端接口的有效性 #

OnlyOffice保存时会向callbackUrl发送POST请求传递修改后的文件，如果Django后端未正确处理该请求，修改无法持久化：

• 打开浏览器Network面板，触发保存后查看是否有向callbackUrl的POST请求，状态码需为200；
• 查看Django日志，确认是否收到回调请求，是否正确解析并覆盖原文件；
• 确保接口允许跨域（OnlyOffice服务器与Django域名不同时），且有权限写入原文件路径。

3. 验证Next.js配置传递的一致性 #

在OnlyOfficeComponent中打印config，对比动态获取的配置与静态HTML中的配置，确保document.key、callbackUrl、token等关键参数完全一致，避免客户端渲染时参数被篡改。

4. 确认token的签名权限 #

动态生成的token如果签名逻辑错误或权限不足，会导致OnlyOffice的回调请求被拒绝：

• 对比静态配置的token与动态返回的token，确认签名时包含document.key、callbackUrl等必要字段；
• 确保token未过期，且权限覆盖保存相关操作。

5. 检查PDF编辑的特殊要求 #

PDF编辑的保存机制与普通文档不同：

• 确保document.url对应的文件可被OnlyOffice服务器访问，回调后该URL能返回最新修改的文件；
• 若使用云存储或CDN，需确认回调后原文件已被覆盖，且缓存已刷新。

快速验证方法 #

将动态获取的配置复制到静态HTML中测试：

• 若静态模式正常，问题出在动态配置传递或后端回调处理；
• 若静态模式也失效，说明配置本身存在错误（如token或key无效）。

内容的提问来源于stack exchange，提问作者Mustafa Alhasanat