Univer 2026 导入导出选 unitId 还是 Snapshot？

4 种导入格式、3 种导出格式：先按文档是否协同来选

Univer 官方格式表列出 4 种导入格式（.xls、.xlsx、.csv、.tsv）和 3 种导出格式（.xlsx、.csv、.tsv）。据此选择 Univer 导入导出路径：需要服务端持久化并进入协同编辑，就优先走 unitId；只需本地或离线处理、格式转换，就优先走 Snapshot。无论选哪条路，都先确认目标格式有对应的转换后端，再验收真实文件的导入和再次导出。具体支持范围以官方 Import and export 文档及项目采用的版本为准。

这篇文章适合准备把 Univer Sheets 接入 SaaS 的前端、全栈开发者，以及负责文件流转的产品技术团队。
如果任务只是离线处理或格式转换，重点看 Snapshot 流程和它仍然依赖的后端。
如果要让用户共同编辑并长期保存文档，则重点核实 unitId、权限和服务端持久化。

先厘清选择条件：在线协同、离线处理还是单纯转换

unitId 与 Snapshot 不是同一份数据的两个命名方式，而是对应不同的文档流程。官方将 unitId 路径用于协同且服务端持久化的文档；Snapshot 路径则适用于无需协同的本地或离线工作流。两条路径的文件交换接口都需要转换后端，因此“没有多人协作”不等于“可以不部署文件转换服务”。

更容易被忽略的，是后端能力、数据所有权和文件兼容性这几项隐性成本：

• 后端依赖不止是导出按钮。文件交换流程涉及上传、转换、任务查询和下载。若只接入前端接口而没有相应的服务端能力，调用链可能无法完成；具体服务端要求可参考官方服务端文档。
• unitId 不是权限凭证。它标识工作簿；用户是否能读取、编辑或导出，仍需由 SaaS 的身份验证、访问控制和文档归属逻辑决定。服务端文档也将权限、存储和文档所有权列为应用需要负责的部分。
• 有标识不等于已验证持久化。协同流程必须确认保存后的内容在重新加载时仍存在，并且再次导出读取的是预期的文档版本。尤其要核查存储实现、服务重启后的数据状态，以及失败任务的处理方式。官方服务端说明提醒，示例中的内存存储在重启后不会保留内容。
• Snapshot 也有处理责任。它返回的是工作簿数据，不是“永远最新”的运行时视图。官方快速入门说明，Snapshot 用于存储数据；需要取得当前文档状态时，应通过 Facade API 保存。具体可查看官方快速入门中的数据保存说明。
• 文件生成成功，不代表复杂内容都往返不变。公式结果、图片、样式和目标软件兼容性应分项检查；是否保留要以目标 SDK、转换后端和样例文件的测试结果为准。

按文档生命周期选择 unitId 或 Snapshot

若导入的工作簿会成为 SaaS 中可反复打开的共享文档，优先走 unitId：官方接口会在启用协同的前提下创建服务端文档并返回标识，随后可以通过协同能力加载。要上线前还需验证文档创建、持久化、访问权限和再次导出环节；只保存一个 unitId 并不能替代业务数据库中的所有权和授权设计。

反过来，如果任务是一次性读取 XLSX、处理数据后生成文件，或是在本地界面中编辑而不共享文档，则 Snapshot 路径通常更合适。导入接口返回 IWorkbookData，可以据此创建工作簿；导出时把保存得到的数据交给 Snapshot 导出接口。工作簿数据仍需要按应用方案保存、恢复，不能把它误当成服务端协同文档。

选择条件	推荐路径	导入后得到什么	上线前要验证什么
文档需服务端持久化，并由用户共同编辑	unitId	服务端文档标识	协同加载、用户权限、服务端保存、再次导出的文档版本
本地或离线处理，不需要共享文档	Snapshot	IWorkbookData	快照保存与恢复、转换服务可用、导出文件可打开
只做文件格式转换	Snapshot 流程可作为选择方向	工作簿数据	转换后端对具体输入和输出格式的支持
尚未确定是否要保留共享文档状态	先明确文档生命周期，再定路径	取决于流程	产品是否需要协同编辑、长期访问与权限管理

表中路径的适用场景和返回数据类型依据官方导入导出接口说明；unitId 是工作簿标识，工作簿可包含多个工作表，这与工作表自身的标识并不相同。需要在应用内索引工作簿和工作表时，可对照Univer Sheets API 对工作簿与工作表的定义。

协同 SaaS：导入后验证标识、访问与再次导出

协同路径常见的实施顺序是：准备转换和协同服务；用户上传文件；调用导入接口取得 unitId；通过协同能力加载文档；保存编辑结果；最后基于目标文档导出文件。导入接口的文件参数可以是浏览器中的 File 对象或远程文件地址，但仍须确认该地址可由实际部署的服务访问，且权限和文件存储满足业务要求。

这里有三个值得单独验收的边界。第一，导入成功只说明当前请求得到结果，不等于文件已按业务要求长期保存。第二，其他用户能否打开文档取决于应用授权，不应仅凭前端拿到了 unitId 就判断权限已配置。第三，再次导出时应确认读取的是预期的已保存内容，而不是尚未提交或未完成转换的状态；关于协同服务的职责边界，可参考官方协同模块说明。

离线工作流：以 Snapshot 处理，再按需求保存数据

Snapshot 适合没有共享文档生命周期的流程：导入文件取得 IWorkbookData，创建工作簿或执行所需处理，再保存快照并交由导出接口生成文件。若业务需要在稍后恢复编辑状态，应由应用选择持久化方式，并保证重建 Univer 实例时注册了处理这些数据所需的插件；Snapshot 本身不会自动提供文档目录、用户权限或服务端协同。

另一个易踩点是直接改 Snapshot 对象，再期待界面或计算状态同步改变。Univer 的文档说明，运行时的数据变更应通过命令或 Facade API 完成；若目标是取得当前状态，应先用对应 API 保存数据。离线处理也要明确数据何时保存、转换失败如何重试，以及导出文件交付给谁。

CSV、TSV：把单表数据导出与完整工作簿分开验收

官方浏览器 API 列出的导入格式为 .xls、.xlsx、.csv、.tsv，导出格式为 .xlsx、.csv、.tsv。其中 CSV 和 TSV 导出针对单个工作表，不保留整个工作簿的多工作表结构和工作簿格式；调用时需要指定格式与工作表标识。因此，CSV/TSV 可用于单表数据交换，但不能被描述为完整工作簿的无损往返。

另外，浏览器 API 对 .xlsm 的支持边界与转换后端能力不能混为一谈：官方格式说明写明，浏览器接口不接受 .xlsm，即使后端支持也不能据此推断前端接口同样接受。接入前要分别核对浏览器 API 与后端实际支持的输入、输出格式，并使用目标用户会上传的文件验证。

格式或内容	官方文档列明的边界	验收时要记录
.xls、.xlsx	列在浏览器导入格式中；具体转换还要求后端支持相应类型	导入是否完成、目标工作簿是否可读取、导出文件能否打开
.csv、.tsv	列在导入和导出格式中；导出针对单个工作表	字符、分隔符、表头、目标工作表及导出内容
.xlsx 导出	列在支持的导出格式中	工作表、公式、图片、样式分别核对，不预设无损兼容
.xlsm	浏览器 API 不接受，即便转换后端支持也不能据此认定浏览器接口可用	明确具体接口边界；若必须支持，验证自定义处理方案

用真实工作簿完成往返验收

验收不要只拿一个空白模板试点下载。优先使用目标用户实际会上传的文件，准备一份包含多个工作表、代表性公式、图片和常用格式的样例；如果真实文件因保密限制不能用于测试，可复制结构并替换数据，同时保留会影响兼容性的功能特征。工作簿包含多个工作表这一数据模型与 API 定义一致，但这些内容能否以预期形式完成文件往返，仍需在目标环境核实。

按以下步骤执行，并把结果按“内容、计算、显示、文件”分类记录：

1. 确认接口边界。对照当前项目使用的 SDK、服务端版本和官方格式说明，记录实际要接收与输出的格式；不要仅根据后端能力推断浏览器接口支持。
2. 准备基准文件。记录工作表名称与顺序、几处代表性单元格、公式文本及预期结果，并标记图片和需要重点检查的格式。
3. 按目标路径导入。协同文档选择 unitId 并核实文档创建与加载；离线处理选择 Snapshot，并确认返回数据能按应用逻辑创建工作簿。
4. 保存并重新读取。协同路径检查持久化后重新加载的内容；Snapshot 路径检查应用保存和恢复的数据。两者都记录失败时的提示与恢复办法。
5. 执行导出。使用实际目标格式生成文件；CSV/TSV 要明确目标工作表，因为它们不是完整多工作表工作簿的替代品。
6. 分项比对结果。逐张核对工作表、抽样核对公式文本与计算结果，再查看图片和格式。若出现差异，分别记录导入、计算、格式或目标软件读取问题，不把所有问题笼统归为“文件坏了”。

公式尤其不应只看单元格显示值：应同时比较公式文本和结果，并在目标运行时确认计算已完成。Univer 的公式文档明确提示，部分计算是异步的；写入公式或数据后，应等待计算结果应用再读取结果。该说明不代表任一外部公式或工作簿都能兼容，复杂公式仍须用项目样例验证。(官方公式功能文档)

图片也应作为独立验收项，分别检查导入后是否显示、保存恢复后是否仍可访问、导出文件中是否存在预期内容。不要只凭编辑器里看得到图片，就认定转换后端已经将图片资源完整写入并能随文件交付。

提交开发验收前逐项勾选

• [ ] 已决定文件要成为服务端协同文档，还是只在本地／离线流程中处理。
• [ ] 选 unitId 时，已确认协同服务、服务端持久化、用户权限和文档再次加载。
• [ ] 选 Snapshot 时，已确认 IWorkbookData 的保存、恢复和导出链路。
• [ ] 已部署或连接文件转换后端，并核实所需格式在浏览器接口与后端两侧均适用。
• [ ] 已单独标注 CSV/TSV 的目标工作表，不把单表导出当作完整工作簿往返。
• [ ] 已用目标用户文件检查多工作表、公式文本、计算结果、图片、格式和文件打开情况。
• [ ] 已分别记录转换失败、权限失败和文件兼容问题的复现条件与处理方式。

文件流转路径定下来后，可以继续阅读官方服务端导入导出架构说明，确认文件交换服务与协同文档之间的边界；其中也明确提到，文件存储、任务状态和访问控制由应用负责。若团队还需要在 macOS 浏览器环境验证前端表现，Mac 测试机可用于补充浏览器回归，但不能替代 Univer 的文件转换后端。

如果当前依赖的是团队共用的本地 Mac，排队等待、环境配置不一致和测试结束后设备闲置，可能让短期验证变得不便；租用 Mac 可以提供独立的临时测试环境，但长期固定负载或必须连接专用物理接口时，自购设备可能更合适。需要临时 macOS 测试环境时，可先查看 nuvcloud 的 Mac mini 方案；它适用于浏览器与前端验证，不会代替你部署转换服务。了解 nuvcloud 的环境入口，可访问 nuvcloud 官网。