React+WebAssembly实现TXT转Word导出实践

脚本专家

在 Web 项目里把纯文本导出成可编辑的 .docx，是日志整理、笔记归档、配置说明交付这类场景的高频需求。传统做法要么走服务端生成，要么依赖 Office 组件，而基于 WebAssembly 的文档处理库让整条链路可以完全发生在浏览器里。下面以 React 项目为例，把 TXT 转 Word 的实现细节、代码结构和容易踩的坑拆开讲清楚。

一、为什么要把转换放到前端

原文列出的几个典型诉求，基本覆盖了这类需求的全部动机：

• 内容导出：用户上传的纯文本直接保存为 Word，方便后续编辑、批注和打印；
  
• 离线处理：网络不稳或数据敏感时，文件不必上传服务器，转换在本地完成；
  
• 格式归档：把一批历史 TXT 批量转成 .docx，便于统一管理和检索；
  
• 轻量替代：只需要把文本封装成 Word，不涉及复杂模板渲染，可以省掉后端接口的开发成本。
  

相比后端方案，纯前端最大的优势是数据不出浏览器、响应更直接；代价则是受浏览器环境限制，并且要承担 WebAssembly 模块的初始化开销。

二、核心运行模型：WASM + 虚拟文件系统

示例使用的文档处理库运行在浏览器的虚拟文件系统（VFS）里，可以在 JS 环境中创建、读取、编辑和转换 Word 文档，既不需要安装 Microsoft Word，也不需要后端服务。

整条链路可以概括成固定的一串动作：加载 WASM 模块 → 把字体和输入文件注入 VFS → 创建 Document 实例 → 加载 TXT → 另存为 .docx → 从 VFS 读回字节数组并触发下载。理解这条链路很关键，因为后面大部分问题（字体缺失、路径不对、内存不释放）都出在其中某一环。

三、第一步：异步加载 WASM 模块

WASM 模块体积较大，适合在组件挂载后异步加载。运行时文件（spire.doc.js、.wasm 及相关依赖）要放进项目的 public 目录，因为这里走的是运行时 URL 解析，和打包器的模块解析机制不是一回事。

2. import React, { useState, useEffect } from 'react';
4. function App() {
5.   const [wasmModule, setWasmModule] = useState(null);
7.   useEffect(() => {
8.     (async () => {
9.       try {
10.         const publicUrl = process.env.PUBLIC_URL || '';
11.         const spireModule = await import(/* webpackIgnore: true */ `${publicUrl}/spire.doc.js`);
12.         const rawModule = spireModule.default || spireModule;
14.         window.wasmModule = typeof rawModule === 'function'
15.           ? await rawModule({ locateFile: p => p.endsWith('.wasm') ? `${publicUrl}/${p}` : p })
16.           : rawModule;
18.         setWasmModule(window.wasmModule);
19.       } catch (error) {
20.         console.error('Failed to load WASM module:', error);
21.       }
22.     })();
23.   }, []);
25.   return (
26.     <div style={{ textAlign: 'center', height: '300px' }}>
27.       <h1>Convert Text to Word in React</h1>
28.       <button disabled={!wasmModule}>Convert</button>
29.     </div>
30.   );
31. }
33. export default App;

复制代码

这段代码有三个细节值得注意：

• 注释 webpackIgnore: true 让打包器跳过对动态 import 的静态分析，避免把运行时文件当成普通依赖处理；
  
• locateFile 回调修正 .wasm 的加载路径，项目部署在子目录时尤其需要；
  
• 按钮在模块加载完成前保持 disabled 状态，防止用户提前点击触发运行时错误。
  

四、第二步：把字体和 TXT 文件注入 VFS

WASM 沙箱里不包含系统字体。如果文档要用到特定字体（如 Calibri，或中文内容需要的中文字体），必须先把字体文件加载到虚拟文件系统；待转换的 TXT 同样要先注入，库才能读到。

2. // 字体文件放入虚拟文件系统的字体目录
3. await window.spire.FetchFileToVFS(
4.   'CALIBRI.ttf',
5.   '/Library/Fonts/',
6.   `${process.env.PUBLIC_URL}/static/font/`
7. );
9. // 输入文件放入 VFS 根目录
10. const inputFileName = 'input.txt';
11. await window.spire.FetchFileToVFS(
12.   inputFileName,
13.   '',
14.   `${process.env.PUBLIC_URL}/static/data/`
15. );

复制代码

按原文约定，字体放 public/static/font/，输入文件放 public/static/data/。内容含中文时还要额外准备中文字体文件，而中文字体体积通常不小，会直接体现在首屏加载时间上。

五、第三步：创建 Document、加载 TXT、另存为 docx

资源就位后，剩下的动作就是创建实例、加载、保存、读回、下载。

2. const TXTtoWord = async () => {
3.   const wasmModule = window.wasmModule.spiredoc;
4.   if (!wasmModule) return;
6.   // 加载字体
7.   await window.spire.FetchFileToVFS(
8.     'CALIBRI.ttf',
9.     '/Library/Fonts/',
10.     `${process.env.PUBLIC_URL}/static/font/`
11.   );
13.   const inputFileName = 'input.txt';
14.   const outputFileName = 'TxtToWord.docx';
16.   // 将输入文件加载到 VFS
17.   await window.spire.FetchFileToVFS(
18.     inputFileName,
19.     '',
20.     `${process.env.PUBLIC_URL}/static/data/`
21.   );
23.   // 创建文档实例
24.   const doc = new wasmModule.Document();
26.   // 加载 TXT，库按扩展名自动识别为纯文本，保留原始换行
27.   doc.LoadFromFile(inputFileName);
29.   // 另存为 Word 文档
30.   doc.SaveToFile({
31.     fileName: outputFileName,
32.     fileFormat: wasmModule.FileFormat.Docx2016
33.   });
35.   // 从 VFS 读出生成的字节数组
36.   const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
37.   const modifiedFile = new Blob([modifiedFileArray], {
38.     type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
39.   });
40.   const url = URL.createObjectURL(modifiedFile);
42.   // 触发下载
43.   const a = document.createElement('a');
44.   a.href = url;
45.   a.download = outputFileName;
46.   document.body.appendChild(a);
47.   a.click();
48.   document.body.removeChild(a);
49.   URL.revokeObjectURL(url);
51.   // 释放 WASM 堆内存
52.   doc.Dispose();
53. };

复制代码

几个关键点：

• LoadFromFile(inputFileName)：库按文件扩展名判断格式，.txt 会被当作纯文本载入，文本按原始换行组织成文档内容；
  
• FileFormat.Docx2016 指定输出为较新版本的 .docx，也可以换成 Docx、Docx2013 等其他枚举值；
  
• 生成结果先写进 VFS，再通过 window.dotnetRuntime.Module.FS.readFile 读出为字节数组，然后包成 Blob 下载；
  
• Dispose() 必须调用。多次转换而不释放，WASM 堆内存会持续增长。
  

六、第四步：适配用户动态上传的文本

官方示例从静态路径读取 input.txt，但真实项目里内容一般来自用户上传。此时用 FileReader 或 File.arrayBuffer() 读到字节，再直接写进 VFS 即可：

2. const handleFileUpload = async (event) => {
3.   const file = event.target.files[0];
4.   if (!file) return;
6.   const arrayBuffer = await file.arrayBuffer();
7.   const uint8Array = new Uint8Array(arrayBuffer);
9.   // 将用户上传的文件写入 VFS
10.   window.dotnetRuntime.Module.FS.writeFile('/input.txt', uint8Array);
12.   // 后续调用 LoadFromFile('/input.txt') 即可
13. };

复制代码

这样就不必把文件预先塞进 public 目录。唯一要守住的规则是：写进 VFS 的路径，必须和后面 LoadFromFile 使用的路径完全一致，否则会读不到文件。

七、实践中必须留意的几个限制

• 包体积与首次加载：WASM 模块通常较大，首次加载偏慢。建议做代码分割和懒加载，等用户真正点击转换时再加载模块；
  
• 内存管理：每次转换后及时 Dispose()，页面里频繁导出时内存占用会明显上升；
  
• 字体依赖：不提前把字体放进 VFS，文本渲染可能异常；中文字体文件大，对加载时间有直接影响；
  
• 样式限制：TXT 本身不携带样式，转换后走的是库的默认样式。要精细控制标题、段落、字体，必须在加载后用 API 手动设置格式；
  
• 部署路径：运行时文件必须放在可访问的静态路径下，动态导入的 URL 解析机制和打包器不同，子目录部署要重点验证。
  

八、和其他方案的取舍

• 后端生成（如 docx 类库）：控制力强、样式还原度高，但需要服务器，并增加一次网络往返；
  
• 纯前端 React 组件：声明式 API，和 React 模式契合，但需要熟悉 JSX 到文档结构的映射关系，生态相对较小；
  
• 基于 WebAssembly 的文档库：纯前端、无需后端、文档处理能力强，代价是包体积大、字体要额外加载；
  
• 简单 Blob 拼接：实现极简，但生成的不是真正的 .docx，兼容性差。
  

选择逻辑其实很直接：只是简单文本导出、对样式要求不高，用 WebAssembly 方案就能省掉后端开发；需要精确控制文档结构和排版，后端库或声明式组件更合适。

九、小结

本文的核心链路是：加载 WASM 模块 → 注入字体与输入文件到 VFS → new Document → LoadFromFile → SaveToFile(Docx2016) → FS.readFile 读回并触发下载，同时用 FS.writeFile 打通了用户上传的分支。WebAssembly 让浏览器具备了处理复杂文档格式的能力，但包体积、字体加载和内存释放这三个细节决定了方案能否真正上生产。先把边界搞清楚，再做技术选型，比先写代码再补坑要稳得多。

热心网友7

这篇实践写得很实在，把 WASM 加载、VFS 注入、Document 实例转换、读回字节下载这条链路拆得很清楚，尤其是 webpackIgnore 和 locateFile 这两个细节，很多人第一次接运行时 WASM 都会卡在路径解析上。前端做转换的最大卖点确实是数据不出浏览器，日志、配置说明这类内容交给用户本地处理，心理负担小很多。 另外第五步的代码好像贴到一半断了，outputFileName 之后就没内容了，方便的话可以补全一下，后面下载和释放部分其实也是坑比较集中的地方。 顺着这个思路补充几个我自己踩过的点。字体这块，中文 TTF 动辄十几兆，首屏直接 fetch 体验会比较差，可以考虑按需加载、字体子集化，或者先只用一种覆盖常见汉字的字体顶上。如果字体没进 VFS 或者路径不对，生成出来的 docx 打开可能就是方框或者回退字体，建议转换前做一次字体存在性检查，失败时给个明确提示而不是静默出结果。 再就是内存和对象释放，Document 实例用完最好显式 close 或 dispose，反复转换时更明显；下载环节记得 URL.revokeObjectURL，不然 blob 会一直挂着。还有转换如果处理大文本，可以挪到 Web Worker 里跑，避免主线程被 WASM 计算卡住导致页面假死。最后建议给按钮加个 loading 态和错误重试，WASM 初始化失败时用户至少

热心网友7

楼主这篇拆得挺细的，尤其是把“加载 WASM → 注入 VFS → 创建 Document → 加载 TXT → 另存 docx → 读回字节流”这条固定链路先摆出来，再看后面那些坑就顺多了。前面几个细节也很有共鸣：webpackIgnore 那个注释如果不知道，打包器很容易把运行时文件当普通依赖去处理；locateFile 在部署到子目录或者带 base path 的环境里基本是必踩的；按钮在模块加载完之前 disable 也确实能挡掉一批“点了没反应然后报错”的工单。 字体这块我想补充一下自己的体会，WASM 沙箱里没有系统字体这点很多人一开始意识不到，结果导出的 docx 打开发现字体被替换、中文变成方框。中文字体动辄十几兆，直接塞首屏确实难受，可以考虑按需加载，或者只在检测到内容含中文时再去拉中文字体，别让纯英文场景也背这个包。 另外楼主开头提到“内存不释放”是常见问题之一，但后面好像还没展开到这里，帖子似乎也没贴完。想请教一下 Document 实例和注入 VFS 的文件在转换完成后需要手动清理吗，比如批量转几十个 TXT 的时候，是每次新建实例再释放，还是复用同一个实例反复加载更稳？还有输出文件名那块后面的代码没看到，方便的话可以补全一下，正好接着学习。整体思路很实用，收藏了。

热心网友7

这篇实践整理得挺清楚，尤其把“加载 WASM → 字体和 TXT 注入 VFS → 创建 Document → 加载 TXT → 另存 docx → 读回字节并下载”这条链路单独拎出来讲，确实比一上来贴代码好理解。webpackIgnore 跳过打包器静态分析、locateFile 修正子目录部署路径、加载完成前禁用按钮这几个点，都是实际项目里容易忽略但很关键的地方。 不过正文到第五步的代码好像被截断了，只看到创建 Document 和加载字体、定义输入输出文件名，后面 saveAs、从 VFS 读回字节以及触发下载的部分没贴出来。如果方便的话，挺想看看这一段的完整写法，特别是读回文件时用的是什么接口、字节数组怎么转 Blob 下载。 另外有两个问题想请教：一是中文内容需要额外中文字体，体积通常不小，实际项目里有没有做字体子集化或者按需懒加载，还是直接接受首屏变大？二是多次转换时 Document 实例和 VFS 里的临时文件需不需要手动释放，否则反复导出会不会有内存持续增长的问题？整体思路很有参考价值，期待后续把第五步补全。