做 DOCX 预览？这个神库别错过

做 DOCX 预览这事，很多人第一反应是"转 PDF 不就完了"。真到项目里一接文件流、一碰批注、一看页眉页脚，味道就不对了。尤其前端页面里想直接把 Word 打开看一眼，产品一句"要跟本地打开差不多"，后面基本就是一串加班。

这类需求我一般先不碰 conversion 服务，先找浏览器里能不能直接渲染。因为一旦把链路拉长成"上传 → 服务端转换 → 存储 → 再预览"，问题就不只是预览了——权限、缓存、转换失败、机器资源都会跟着来。很多时候用户只是想在页面里看个 docx，没必要先把系统搞重。

先说库：docx-preview 是什么

docx-preview 是一个纯前端的 .docx 文件预览库，核心能力是把 Word 文档解析后直接渲染为 HTML。它不是拿来编辑的，是拿来预览的，定位很老实：把 docx 在浏览器里尽快摊开给你看。

它的技术本质是使用 jszip 解析 OOXML 格式的 docx 文件包，提取文档.xml、样式.xml、关系文件等组件，再通过 DOM 渲染重建文档结构。由于完全运行在浏览器端，不依赖任何服务端组件，也不需要调用外部转换 API。

适用场景非常明确： - 合同查看与审核系统 - 简历在线预览 - 导出的 Word 文档分享 - 审批流附件预览 - 知识库文档查阅

这些场景共同的特点是：用户只需要"能看"，不需要"能改"。一旦产品说"必须和 Office 打开效果完全一致"或者要"批注、修订、协同编辑"，就到了这个库的边界。

安装与最小化引入

通过 npm 安装：

npm i docx-preview

最简引入只需要三行代码。假设页面结构是这样的：

<input id="file" type="file" accept=".docx" />
<div id="preview"></div>

JavaScript 端这样写：

import { renderAsync } from 'docx-preview'

const input = document.getElementById('file')
const container = document.getElementById('preview')

input.addEventListener('change', async (e) => {
  const file = e.target.files?.[0]
  if (!file) return

  if (!file.name.endsWith('.docx')) {
    alert('这里只支持 docx')
    return
  }

  container[xss_clean] = '解析中...'

  try {
    const buffer = await file.arrayBuffer()

    await renderAsync(buffer, container, null, {
      className: 'word-wrap',
      inWrapper: true,
      ignoreWidth: false,
      ignoreHeight: false,
      breakPages: true,
      ignoreFonts: false
    })
  } catch (err) {
    console.error('docx 预览失败:', err)
    container[xss_clean] = '<div>文件解析失败</div>'
  }
})

这段代码的核心是 renderAsync 函数，它接收三个参数： - buffer: docx 文件的 ArrayBuffer - container: 渲染目标的 DOM 元素 - options: 渲染配置对象

配置项中 breakPages: true 开启分页渲染，inWrapper: true 让文档内容包裹在容器内，ignoreFonts: false 保留字体样式。实测这些默认值对大多数文档已经够用，不需要特别调优。

核心渲染流程解析

理解 docx-preview 的工作原理，有助于在遇到问题时快速定位。

mermaid flowchart TD
    A[用户选择 .docx 文件] --> B[file.arrayBuffer 读取文件]
    B --> C[jszip 解析 OOXML 包]
    C --> D[提取 document.xml 文档内容]
    C --> E[提取 styles.xml 样式定义]
    C --> F[提取 relationships 关系数据]
    D --> G[DOM 重建 + 样式映射]
    E --> G
    F --> G
    G --> H[渲染到目标容器]

整个渲染流程分为四个阶段：

第一阶段：文件读取。通过 FileReader 或 input.files 获取文件的二进制数据，转换为 ArrayBuffer 供后续解析。

第二阶段：OOXML 解析。docx 本质上是一个 zip 包，内部包含多个 XML 文件。jszip 负责解压并提取这些文件，其中最核心的是 word/document.xml——它包含了文档的正文内容和结构。

第三阶段：样式映射。从 word/styles.xml 提取段落样式、字符样式列表，建立 CSS 属性与 Word 样式名称的映射表。heading1 对应 font-size: 28px; font-weight: bold，emphasis 对应 font-style: italic 等等。

第四阶段：DOM 渲染。根据 XML 节点类型创建对应的 HTML 元素，附加相应的 CSS 类名或行内样式，最终形成可阅读的 HTML 文档片段。

远程文件预览：fetch + blob 方案

很多系统不是本地上传，而是点"查看附件"加载远端文件。这时候不走 input 了，需要自己 fetch 二进制数据：

import { renderAsync } from 'docx-preview'

async function previewRemoteDocx(url, container, token) {
  container[xss_clean] = '<div style="padding:20px">加载中...</div>'

  const res = await fetch(url, {
    headers: {
      Authorization: `Bearer ${token}`
    }
  })

  if (!res.ok) {
    throw new Error(`文件下载失败: ${res.status}`)
  }

  const blob = await res.blob()
  const buffer = await blob.arrayBuffer()

  await renderAsync(buffer, container, null, {
    inWrapper: true,
    breakPages: true
  })
}

// 调用示例
previewRemoteDocx(
  'https://api.example.com/docs/contract.docx',
  document.getElementById('preview'),
  localStorage.getItem('token')
)

这里有一个细节：Bearer Token 通过 Authorization 请求头传递，而非直接暴露在 URL 中。如果你们的接口要求在 URL 参数里传 token，或者有特殊的签名机制，需要相应调整。

对于大文件，建议加上 loading 状态和超时控制：

async function previewWithTimeout(url, container, options = {}, timeout = 30000) {
  const controller = new AbortController()
  const timer = setTimeout(() => controller.abort(), timeout)

  try {
    const res = await fetch(url, {
      ...options,
      signal: controller.signal
    })
    clearTimeout(timer)

    if (!res.ok) throw new Error(`HTTP ${res.status}`)

    const blob = await res.blob()
    const buffer = await blob.arrayBuffer()

    await renderAsync(buffer, container, null, {
      inWrapper: true,
      breakPages: true,
      ...options.renderOptions
    })
  } catch (err) {
    container[xss_clean] = `<div style="color:red;padding:20px">加载失败: ${err.message}</div>`
    throw err
  }
}

超时机制使用 AbortController 实现，这是 Fetch API 的标准做法，30 秒对于大多数文档预览场景够用了。

样式隔离：防止全局样式污染

docx-preview 渲染出来的是一堆 HTML，丢进现有页面后容易被全局样式污染。尤其当项目里有这种全局规则时：

/* 项目全局样式 */
div {
  box-sizing: border-box;
}

p {
  margin: 0;
  line-height: 1.5;
}

table {
  border-collapse: collapse;
}

这些规则会直接干预 docx 预览的渲染结果，导致段落间距、表格边框等细节走样。解决方案是给预览容器加一层独立的样式隔离：

#preview {
  padding: 24px;
  overflow: auto;
  background: #f5f7fa;
  min-height: 400px;
}

#preview .word-wrap {
  background: #ffffff;
  padding: 32px;
  box-shadow: 0 2px 8px rgba(0,0,0,0.08);
  max-width: 900px;
  margin: 0 auto;
}

/* 隔离业务全局样式的影响 */
#preview p {
  margin: inherit;
  line-height: inherit;
}

#preview div {
  box-sizing: content-box;
}

#preview table {
  border-collapse: separate;
  border-spacing: 0;
}

核心思路是两步：

1. 创建独立命名空间：预览容器使用特定 ID，其内部元素的选择器都以 #preview 开头，避免被项目全局选择器覆盖。

2. 重置冲突属性：对于 box-sizing、margin、border-collapse 等容易冲突的属性，显式重置为文档渲染需要的样子。

边界场景与排坑指南

.doc 和 .docx 的区别

docx-preview 只能处理 .docx 格式，不能处理老的 .doc 格式。判断方法是检查文件头魔术字节：.docx 文件以 PK（50 4B）开头（因为它是 zip 压缩包），而 .doc 文件以 D0 CF 开头（OLE2 复合文档）。

如果你的系统需要兼容老格式，有两条路：

function isDocx(file) {
  return file.name.endsWith('.docx')
}

function getFileTypeNote(file) {
  if (file.name.endsWith('.doc')) {
    return '检测到 .doc 文件，需先转换为 .docx 格式再预览'
  }
  if (!file.name.endsWith('.docx')) {
    return '仅支持 .docx 格式'
  }
  return null
}

分页渲染与长文档

breakPages: true 会保留 Word 文档的分页结构。但这不一定是好事——如果你的预览区域高度固定，分页会导致内容溢出。通常的做法是改成连续渲染模式：

await renderAsync(buffer, container, null, {
  breakPages: false,  // 关闭分页，连续渲染
  inWrapper: true
})

同时给容器加一个最大高度并允许滚动：

#preview {
  max-height: 600px;
  overflow-y: auto;
}

图片渲染

docx 里的图片以 base64 内联或关系引用的方式存在。docx-preview 默认会自动渲染图片，但需要注意：

• 如果图片是外部链接（非内联），需要确保 CORS 配置允许 fetch
• 超大图片会被缩放到容器宽度，可能会糊
• EMZ/WMZ 格式的 Word 剪贴画不会被支持，会显示为空

页眉页脚与复杂排版

docx-preview 对页眉页脚的支持有限。如果文档使用了复杂的页眉页脚（奇偶页不同、章节起始不同等），渲染结果可能和 Word 打开不一致。对于大多数"只是看看"的需求，这个差异可接受；对于合同等正式文档，建议在文档说明里加一句"以下载的原始文件为准"。

实战：构建一个完整的文档预览组件

下面是一个相对完整的实现，包含了前面讨论的所有要点：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>文档预览组件</title>
  <style>
    * { box-sizing: border-box; margin: 0; padding: 0; }

    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      background: #f0f2f5;
      padding: 20px;
    }

    .preview-header {
      background: #fff;
      padding: 16px 24px;
      border-radius: 8px;
      margin-bottom: 16px;
      display: flex;
      align-items: center;
      gap: 16px;
      box-shadow: 0 1px 3px rgba(0,0,0,0.08);
    }

    .file-input-wrapper {
      position: relative;
    }

    .file-input-wrapper input[type="file"] {
      position: absolute;
      opacity: 0;
      width: 100%;
      height: 100%;
      cursor: pointer;
    }

    .upload-btn {
      background: #1890ff;
      color: #fff;
      border: none;
      padding: 10px 20px;
      border-radius: 6px;
      cursor: pointer;
      font-size: 14px;
      white-space: nowrap;
    }

    .upload-btn:hover {
      background: #40a9ff;
    }

    .file-name {
      color: #666;
      font-size: 14px;
    }

    #preview {
      background: #fff;
      border-radius: 8px;
      box-shadow: 0 1px 3px rgba(0,0,0,0.08);
      min-height: 400px;
    }

    #preview .loading {
      padding: 60px;
      text-align: center;
      color: #999;
    }

    #preview .error {
      padding: 60px;
      text-align: center;
      color: #ff4d4f;
    }

    #preview .word-wrap {
      background: #fff;
      padding: 32px;
      max-width: 900px;
      margin: 0 auto;
    }

    /* 样式隔离 */
    #preview .word-wrap p {
      margin: inherit;
      line-height: inherit;
    }

    #preview .word-wrap div {
      box-sizing: content-box;
    }

    #preview .word-wrap table {
      border-collapse: separate;
      border-spacing: 0;
    }
  </style>
</head>
<body>
  <div class="preview-header">
    <div class="file-input-wrapper">
      <input type="file" id="fileInput" accept=".docx">
      <button class="upload-btn">选择 .docx 文件</button>
    </div>
    <span class="file-name" id="fileName">暂未选择文件</span>
  </div>

  <div id="preview">
    <div class="loading">请选择一个 Word 文档</div>
  </div>

  <script type="module">
    import { renderAsync } from 'docx-preview'

    const fileInput = document.getElementById('fileInput')
    const preview = document.getElementById('preview')
    const fileName = document.getElementById('fileName')

    fileInput.addEventListener('change', async (e) => {
      const file = e.target.files?.[0]
      if (!file) return

      if (!file.name.endsWith('.docx')) {
        preview[xss_clean] = '<div class="error">仅支持 .docx 格式文件</div>'
        return
      }

      fileName.textContent = file.name
      preview[xss_clean] = '<div class="loading">正在解析文档...</div>'

      try {
        const buffer = await file.arrayBuffer()
        preview[xss_clean] = ''

        await renderAsync(buffer, preview, null, {
          className: 'word-wrap',
          inWrapper: true,
          breakPages: false,
          ignoreFonts: true
        })
      } catch (err) {
        console.error('预览失败:', err)
        preview[xss_clean] = `<div class="error">解析失败: ${err.message}</div>`
      }
    })
  </script>
</body>
</html>

这个组件实现了： - 文件选择与格式校验 - Loading 状态展示 - 错误处理与显示 - 样式隔离 - 连续渲染模式

什么时候不该用它

docx-preview 是一个轻量预览方案，有它的边界：

到了"必须和 Office 完全一致"或者需要批注修订这一步，就不是一个前端预览库能兜住的了。该上服务端转换（LibreOffice / Microsoft Graph API）就上，该买商业方案就买。

总结

docx-preview 这个库不花哨，定位老实：把 docx 在浏览器里尽快摊开给你看。它适合.docx 文件的合同查看、简历预览、导出的 Word 在线查看、审批流附件预览这些场景。

前端自己接一下就能落地，不用先上 LibreOffice，不用单独搞文档转换服务，部署会轻很多。很多需求，做到这里，已经够用了。

长按二维码关注 “边学边练”