协同编辑（co-editing）让多个用户同时打开同一份文档，任何人的修改都能被其他人看到，而不需要来回传文件、手动合并。Spire.OfficeJS 内置了协同能力：只要页面配置得当，就能让两个浏览器标签、两个用户进入同一次编辑会话。本文以 Word 为例，先讲清协同的原理与前提，再逐一展开关键配置，最后给出完整可运行的示例。

• 协同编辑
  • 协同编辑工作原理
  • 启动协同的前提
  • 协同标识：fileInfo.primary
  • 快速模式与严格模式
  • 协同服务地址：coAuthorUrl
  • 快速上手：两个人同时编辑同一份文档
  • 常见问题

协同编辑工作原理

下列图示和步骤解释了在 Spire.OfficeJS 中如何协同编辑文档。

1. 用户 1 和用户 2 用同一个协同标识打开文档（即相同的 fileInfo.primary）。
2. 用户 1 修改文档。
3. 编辑器把修改上报给协同服务（即 coAuthorUrl 指向的服务）。
4. 协同服务把修改分发给用户 2 的编辑器。
5. 用户 2 的编辑器应用这些修改，于是同样的内容出现在两个人的屏幕上。

最关键的是：同一次协同会话必须使用同一个 primary。此外还要连接 Office Server（见 启动协同的前提），其余都是围绕它们的配置与状态管理。

很多人第一次接触在线编辑时会以为：浏览器直接编辑服务器上的 Word 文件。实际并非如此。Spire.OfficeJS 编辑的是内部缓存的编辑文件（Editor.bin），而不是原始 Word 文件：

启动协同的前提

协同不是“把编辑器嵌进页面就会自动生效”的。要让两个用户进入同一次协同会话、看到彼此的修改，必须同时满足两个条件：

1. 同一个 primary：fileInfo.primary 不是一个普通的“文件 ID”，而是当前协同编辑版本的身份证。要保证 fileInfo.primary 相同（原理与生成方式见 协同标识：fileInfo.primary）。
2. 连接 Office Server：编辑器需要连接 Office Server（本地启动或远程部署均可），并用 coAuthorUrl 指定其地址（见 协同服务地址：coAuthorUrl）。

两者缺一不可：primary 不同，会进入两次独立会话。没有协同服务，修改根本没有分发通道。

最简单的验证方式：用同一个 fileInfo.primary、不同的 user.id 分别在两个标签页打开页面。只要 primary 一致，它们就会进入同一次协同会话，相当于“和自己协同”。

协同标识：fileInfo.primary

fileInfo.primary 是 Spire.OfficeJS 判断 “这是不是同一份正在协同的文档” 的唯一依据。所有参与者必须使用同一个值，才能进入同一次协同会话。

生成与复用

• 必须由页面显式提供，且对同一会话稳定不变。 如果不填，Spire.OfficeJS 会随机生成一个，每个用户每次打开都会得到不同的值，结果就是各自独立、互不同步。
• 字符集：默认随机生成的值由小写字母和数字组成，长度约 20 位。
• 不要复用：一份文档的“一次编辑会话”对应一个 primary，新的编辑轮次应换新值。

保存完成后，建议在下一次打开该文档时使用新的 primary：把“已保存的内容”与“新一轮协同”隔离开，避免上一轮会话的缓存、版本和新的修改混在一起。若沿用旧值反复编辑，容易出现内容回退或同步异常。

轮换 primary 的同时，还要把 sourceUrl 指向本轮保存后的文件（通常是 onSave 拿到的文件地址）。否则新 primary 首次打开会重新下载并转换旧的原始文件，刚保存的内容就丢了。

快速模式与严格模式

Spire.OfficeJS 提供两种协同模式：快速模式与严格模式。界面上通过“审阅 → 协同编辑模式”或“文件 → 设置 → 协同编辑模式”切换。两者都能让多人进入同一次会话，区别在于修改什么时候同步、由谁触发保存：快速模式边改边同步，严格模式先各改各的、保存时才合并。

快速模式（默认）

快速模式下，任何人的修改都实时广播给所有参与者：文字、光标位置和选中区域立即可见，无需保存。编辑某个区域（段落、单元格等）前，编辑器会先获取该区域的块锁，其他人会看到该区域被占用，直到编辑完成或释放锁。

严格模式

严格模式下，每个人都在各自隔离的副本中编辑，但仍属于同一次协同会话：他人的修改在保存前保持隐藏，多人同时编辑的区域会用不同颜色的虚线标记。点击“保存”后，整份文档才提交给协同服务合并。

两种模式对比

配置默认模式

通过 user.customization.public.common 下的两个开关控制：

user: {
  customization: {
    public: {
      common: {
        CollaborationModeIsFast: true,  // 打开即进入快速模式
        CollaborationModeOnlyFast: false
      }
    }
  }
}

• CollaborationModeIsFast：打开文档时的初始模式。true 为快速模式，false 为严格模式。快速模式是默认值。
• CollaborationModeOnlyFast：设为 true 时锁定快速模式，“协同编辑模式”里的严格选项会被禁用，用户无法切换到严格模式。适合要求所有人始终实时共享的场景。

协同服务地址：coAuthorUrl

coAuthorUrl 指向提供协同能力的编辑器服务（Office Server），必须显式配置。它配置在 editorAttrs.serverless 下，代码示例如下：

editorAttrs: {
  useWebAssemblyDoc: true,
  serverless: {
    useServerless: true,
    baseUrl: 'https://LocalExample:3000',    // 前端资源（web 目录）的地址
    coAuthorUrl: 'https://LocalExample:8000' // 协同服务（Office Server）地址
  }
}

注意区分三类地址：SpireCloudEditor.js 的加载地址和 baseUrl 只决定前端资源从哪里加载，不等于协同服务地址。coAuthorUrl 必须指向浏览器可达的 Office Server，否则也无法实现协同。

快速上手：两个人同时编辑同一份文档

这一节把前面的内容拼成一个最小可运行页面：替换脚本地址、服务地址、文档地址、用户信息和保存处理即可。

页面结构

在页面里放一个容器 div，再引入 Spire.OfficeJS 的编辑器脚本：

<div id="editor"></div>

<!-- 编辑器脚本由你的 Spire.OfficeJS 服务提供 -->
<script src="https://LocalExample:3000/web/editors/spireapi/SpireCloudEditor.js"></script>

初始化配置

<script>
  // 协同会话 primary：同一份文档、同一次协同，所有用户必须一致
  const DOC_PRIMARY = 'a1b2c3d4e5f6g7h8i9j0';

  // 当前用户：id 必须唯一且稳定，name 是协作时显示的称呼
  const currentUser = {
    id: 'user-1001', 
    name: '张三'
  };

  const config = {
    fileAttrs: {
      fileInfo: {
        name: '项目方案.docx',
        ext: 'docx',
        primary: DOC_PRIMARY // 协同会话 primary
      },
      sourceUrl: 'https://your-file-host/files/project-plan.docx'
    },
    user: {
      id: currentUser.id,
      name: currentUser.name,
      customization: {
        public: {
          common: {
            CollaborationModeIsFast: true, // 打开即进入快速模式
            CollaborationModeOnlyFast: false
          }
        }
      }
    },
    editorAttrs: {
      useWebAssemblyDoc: true,
      serverless: {
        useServerless: true,
        baseUrl: 'https://LocalExample:3000',    // 前端资源（web 目录）的地址
        coAuthorUrl: 'https://LocalExample:8000' // 协同服务（Office Server）地址
      },
      editorMode: 'edit',
      editorType: 'document',
      editorWidth: '100%',
      editorHeight: '800px',
      viewLanguage: 'zh',
      canEdit: true,
      canReview: true,
      canComment: true,
      canChat: true,
      events: {
        // 保存时由页面自行处理：event.data[1] 是当前文档的 File 对象
        onSave: function (event) {
          const fileName = event.data[0];
          const file = event.data[1];

          const form = new FormData();
          form.append('file', file, fileName);
          form.append('primary', DOC_PRIMARY);
          fetch('https://your-file-host/save-file', {
            method: 'POST',
            body: form
          });
        }
      }
    }
  };

  new SpireCloudEditor.OpenApi('editor', config);
</script>

常见问题

两个用户各自打开，改动却互不同步

按优先级排查：

1. fileAttrs.fileInfo.primary 是否相同。不同的 primary 会进入两个独立会话，即使 sourceUrl 完全一样也不会同步。
2. 是否配置并连接了 Office Server。editorAttrs.serverless.coAuthorUrl 必须指向浏览器可达的 Office Server：本地启动（如 http://127.0.0.1:8000）或远程部署均可。没配或配错就无法协同（见协同服务地址：coAuthorUrl）。
3. sourceUrl 只在首次打开或缓存未命中时生效。同一 primary 命中缓存后不再读取它。需要换文件时，应同时更新 sourceUrl 并换用新的 primary。

看不到“协同编辑模式”入口

入口需要 editorMode: 'edit'。

快速模式下无法撤销 / 重做

这是快速模式的设计行为：改动已实时广播并自动同步，无法单端回退。需要撤销历史时，切换到严格模式，在隔离副本中编辑再保存。

保存后协同异常或内容回退

多半是复用了旧的 primary。保存完成后（onSave 已收到文件），下一次打开该文档时应换用新的 primary，并把 sourceUrl 指向保存后的文件，不要把已完成保存的旧值继续用于新会话。