基于 Django 给 wangEditor 实现 PDF 公文解析导入

在政务办公类系统里，wangEditor 已经是很常见的富文本编辑器了，但真正做起来就会发现一个痛点：很多公文、通知、红头文件都是以 PDF 形式存在的，而 wangEditor 本身只能处理 HTML 内容，PDF 根本没法直接拖进去编辑。用户表面上提的是“导入 PDF”，实际上背后还跟着一连串需求：要能把公文的正文文字稳定提取出来、要能自动清理页眉页脚和页码、要能按阅读顺序插入编辑器、最好解析完还能一键切到只读模式去核对原件。

这篇文章就是围绕“给 wangEditor 加一个导入 PDF 解析政府公文内容”这个真实场景展开的。我会把技术边界、解析原理、Django 后端的接口实现、wangEditor 端的接入方式，以及我在实操里踩过的坑一步步讲清楚。内容偏向有基础但没做过类似功能的开发者，如果你正在给编辑器接 pdf.js、想用 Django 做 PDF 解析接口，或者被 wangEditor 的 customUpload、只读模式折腾过，这篇文章可以直接帮你少走弯路。

1. 先搞清边界：为什么 PDF 不能直接进 wangEditor

刚接到这个需求时，很多人第一反应是“做个导入按钮，选完 PDF 后把文件塞进编辑器不就行了”。这个想法其实方向就错了。要打通链路，必须先搞清楚 wangEditor 到底在编辑什么。

1.1 wangEditor 只认 HTML，不认 PDF 文件

wangEditor 从 v4 到 v5，核心都是一个基于 contenteditable 的富文本编辑区。你在页面上看到的所有加粗、标题、段落，最终都会序列化成一段 HTML 字符串，比如 <p>正文内容</p>。你调 editor.getHtml()，拿到的就是这段 HTML；编辑器把内容渲染出来，依赖的也是这段 HTML。

PDF 在这里是一个完全不同的东西。PDF 是版式文档，它记录的是“哪个字符放在页面哪个位置”，而不是“这篇文章有哪些段落、哪些是标题、哪些需要加粗”。也就是说，PDF 文件本身没有一个通用的“正文结构”，不能像 DOCX 那样被编辑器直接解析成文档对象模型。PDF 想进 wangEditor，只能走一条路：先用解析工具把 PDF 里的文本内容抽出来，再转成 HTML 片段插进编辑器。

我在项目里给用户演示的时候，经常打一个比方：PDF 是一张已经印刷好的报纸，你没办法把一个编辑框直接“装进”这张报纸里继续写字，只能把报纸上的字先敲成电子文稿，再粘贴到编辑框里。这个“敲成电子文稿”的动作，就是我们技术侧要解决的 PDF 解析。

1.2 PDF 的内部形态和普通文档完全不同

PDF 的存储结构跟文本文件是两回事。你打开一个 PDF 文件，里面看到的是一堆对象和绘制指令，比如 BT ... Tj ... ET 这种文本绘制操作符，每个字符经常带着一个坐标位置。PDF 阅读器之所以能按顺序显示文字，是因为它根据这些坐标把字形一个个画在页面上。

这就带来很多用户感知不到、但开发时必须处理的麻烦：

• PDF 里的文字顺序不一定是阅读顺序。如果 PDF 是从某个排版软件导出的，文本块顺序可能和视觉顺序不一致。
• 两栏排版的公文（比如附件里的表格说明），按文件内部对象顺序抽取文本时，左栏和右栏内容会交叉混在一起。
• 页眉、页脚、页码对阅读者来说是辅助信息，但 PDF 解析时就是普通文本，会混进正文章节里。
• 扫描件 PDF 本质上是一张张图片，里面根本没有文本层，常规解析工具抽出来的是空内容或乱码，必须走 OCR。

所以，一个“能打开 PDF 并复制文字”的工具，并不等于一个“能正确解析公文内容到编辑器”的工具。只调一个现成 SDK 拿到一串 text 就完事，后面一定会在页面效果上翻车。

1.3 解析放在后端而不是前端的三个理由

PDF 解析存在两种常见做法，一种是在前端直接用 pdf.js 把文本抽出来，另一种是把 PDF 上传到后端解析。我这次选的是后端解析，原因很直接：

第一，公文内容经常涉及格式二次加工，比如要识别标题、落款、发文字号，还要做页眉页脚过滤。这些规则写在后端可以统一维护，前端只是把解析结果展示出来。一旦改成前端解析，每次调整策略都要发版，浏览器兼容性也会成为新问题。

第二，政务类项目很多是内网部署，浏览器环境未必都是最新版本，pdf.js 在某些老版本浏览器里的兼容问题够你排查一整天的。而 Python 后端装的解析库跑在服务器上，和浏览器无关，只要把最终文本回传前端就行。

第三，同一个 PDF 往往不只会导入 wangEditor，还要给其他系统复用。解析能力做成独立后端服务后，不管前端是 wangEditor、Vue 还是移动端 H5，都能通过同一个接口拿到解析文本。

方案定下来，整个技术链路就很清晰了：wangEditor 页面前端选择本地 PDF，把文件上传到 Django 后端；Django 调用 PDF 解析库提取文本并清洗；解析结果以 JSON 格式返回；前端拿到 text 后调用 wangEditor 的 API 插入编辑区。接下来我把每个环节拆开来讲。

2. PDF 解析的核心：顺序、页眉过滤与脏数据

后端解析这一步是整个需求的关键，也是最容易反复返工的地方。这里不建议用那种简单把整页文本一次性导出的 API，因为公文这种版式文档一旦出现双栏、页眉、页码，一次性导出的文本就是一团乱麻。我们要先拿到每个文本行的坐标，再自己做排序和过滤。

2.1 用 PyMuPDF 拿坐标，按阅读顺序重排

我选的是 Python 的 PyMuPDF 库，import fitz。这个库速度快，能拿到文本块、行、字级别的位置信息，非常适合做版面分析。核心思路是：遍历每一页，拿到页面里的所有文本行及其包围盒 bbox，然后把行按 (y0, x0) 排序，y0 是行顶部的 y 坐标，x0 是行左侧的 x 坐标。这样做能最大程度还原人的阅读顺序。

直接上一个可以跑通的基础版本：

python复制import fitz

def extract_pdf_text(path: str) -> list[str]:
    doc = fitz.open(path)
    ordered_lines = []
    for page in doc:
        # 页面上的文本块都带 bbox，结构是 dict
        blocks = page.get_text("dict")["blocks"]
        page_lines = []
        for block in blocks:
            if block["type"] != 0:   # 0 表示文本块，图片块直接跳过
                continue
            for line in block["lines"]:
                y0 = round(line["bbox"][1], 1)
                x0 = round(line["bbox"][0], 1)
                text = "".join([span["text"] for span in line["spans"]]).strip()
                if text:
                    page_lines.append((y0, x0, text))
        # 这一页内部先按行排序，跨页之间也按页序追加
        page_lines.sort(key=lambda item: (item[0], item[1]))
        ordered_lines.extend([item[2] for item in page_lines])
    doc.close()
    return ordered_lines

这里有几个很实际的经验：

• 不要直接用 page.get_text() 拿全文。那返回的就是 PDF 内部对象顺序，往往不是排版顺序，尤其是跨栏时一定错乱。
• 排序时先按 y 再按 x 是“通栏文档”的标准做法。遇到两栏公文，仅按 y 排序还不够，后面会讲怎么处理。
• line["spans"] 里拿到的文本可能被拆成多个 span，比如一个字一个 span，所以要用 "".join(...) 拼起来再处理。

做完这一步，你已经能拿到一个基本可读的文本行列表，但它还不能直接进编辑器，因为页眉、页码、表格这些噪声还混在里面。

2.2 页码范围与公共页眉的过滤

政府公文的 PDF 基本都有页眉，格式一般是“文件名称 + 发文字号”或者“某某单位办公会议纪要”。这类内容出现在每一页的顶部，如果不过滤，解析结果里会穿插几十行重复文字，回填到 wangEditor 之后非常难看。

常规做法是统计文本行的出现频率。一个文本行如果跨页出现的次数超过总页数的一半，基本可以判定是页眉或者页脚。我写了一个简单的统计过滤：

python复制from collections import Counter

def remove_common_noise(ordered_lines: list[str], total_pages: int) -> list[str]:
    """删除跨页反复出现的公共行，比如页眉、页脚、页码"""
    counter = Counter(ordered_lines)
    noise_texts = {
        text for text, count in counter.items()
        if count >= max(2, int(total_pages * 0.5)) and len(text) < 50
    }
    return [line for line in ordered_lines if line not in noise_texts]

但这里我要提醒一点：自动过滤不能做得太“聪明”，否则会误伤正文。我遇到过一份很短的转发性通知，正文就 3 页纸，第二页顶部出现了一行和页眉几乎相同的文字，其实那是文件标题的延续。自动过滤把关不了所有语义层面的判断，所以在这个项目里，我最终给管理端加了一个“过滤词库”和“保留词库”配置，让运营人员可以微调。

页码的过滤规则就简单很多。公文页码通常只有数字，可能带一个横线，比如 - 1 -。这类行直接用正则判断：

python复制import re

def is_page_number(text: str) -> bool:
    # 纯数字、前后带上横线或空格，基本可以判定是页码
    cleaned = text.strip().strip("-_—|")
    return bool(re.fullmatch(r"\d{1,3}", cleaned))

这个规则在绝大多数场景下够用，而且不会误伤正文，因为正文里很少有单独一行只写一个数字的情况。

2.3 多栏和表格内容怎么处理才不翻车

真正的考验在双栏排版。有些公文的附件里有双栏说明，比如左侧一列名词解释、右侧一列对应的内容。如果你只按 (y0, x0) 排序，页面左栏先是第一行，然后右栏第一行紧随其后，再左栏第二行、右栏第二行……最终出来的文本一行左一行右，阅读时来回跳，用户直接懵。

处理这类问题，我的做法是先判断页面是不是多栏布局：统计页面上所有文本行的 x 坐标分布，看这些 x 是否明显聚集在两个或多个区域。如果有明显的聚类，就需要按栏分组排序，而不是简单按 y 排：

python复制def group_lines_by_column(lines, gap_threshold=40):
    # lines: [(y0, x0, text)]
    # 按 x0 排序后看相邻列间距，间距明显偏大的位置就是一栏的分界
    lines_sorted_by_x = sorted(lines, key=lambda item: item[1])
    columns = []
    current = [lines_sorted_by_x[0]]
    for prev, cur in zip(lines_sorted_by_x, lines_sorted_by_x[1:]):
        if cur[1] - prev[1] > gap_threshold:
            columns.append(current)
            current = []
        current.append(cur)
    columns.append(current)
    # 每栏内部再按 y 排序，最后按栏目从左到右输出
    result = []
    for column in columns:
        column.sort(key=lambda item: (item[0], item[1]))
        result.extend([item[2] for item in column])
    return result

这段代码是个朴素的聚类方法，实际项目里还要结合每个文本行的宽度来判断，因为公文里左栏和右栏之间往往不像报纸那么严格对齐。但思路是对的：先分栏，再在栏内按阅读顺序排序。

表格更麻烦。PDF 里表格的文本，如果不用专门的表格解析策略，抽出来基本是竖着读的。比如单元格 A 在表格左上角、B 在 A 下方，按行排序后 A 和同行右侧的 C 会一起输出，但 B 和 C 本来不在同一行，语义就丢了。pdfplumber 在处理规则表格时比 PyMuPDF 表现更好，它能把单元格按行列网格关系还原出来。但在公文导入这个场景里，我建议不要指望解析工具把复杂表格 100% 还原成 HTML 表格，实际项目中更稳妥的做法是：正文按 PDF 文本流导入，表格类的页面单独提示用户“当前为非纯文本版式，建议结合原 PDF 核对”，在解析结果里用占位符标记。

这不代表技术不行，而是投入产出比的问题。为了少数复杂表格，把解析逻辑做到肉眼无法辨别的还原程度，在政务项目里往往不值得。识别到这类内容后做好标注，保留 PDF 原件供用户查看，反而是更负责任的做法。

3. Django 解析服务 API 实现与避坑

服务端解析模块独立出来后，接下来就是把它的能力暴露成 HTTP 接口给 wangEditor 前端调用。这里我用 Django 实现，因为热词场景里也涉及 django pip wangeditor，说明很多团队的前后端是这么搭配的。

3.1 接口约定与视图实现

接口设计没必要做得很花哨。前端通过 multipart/form-data 上传一个 file 字段，后端解析完成后返回 JSON。我的返回结构统一是：

json复制{
  "code": 0,
  "message": "ok",
  "data": {
    "content": "解析后的纯文本内容",
    "pages": 12,
    "filename": "某某文件.pdf"
  }
}

Django 视图代码长这样：

python复制import os
import tempfile
from django.http import JsonResponse
from django.views import View
from django.utils.decorators import method_decorator
from django.views.decorators.csrf import csrf_exempt

from .parser import extract_and_clean_pdf

@method_decorator(csrf_exempt, name="dispatch")
class PDFParseView(View):
    def post(self, request):
        upload_file = request.FILES.get("file")
        if not upload_file:
            return JsonResponse({"code": 1, "message": "未接收到文件"}, status=400)

        filename = upload_file.name
        if not filename.lower().endswith(".pdf"):
            return JsonResponse({"code": 1, "message": "仅支持 PDF 文件"}, status=400)

        # 限制文件大小，避免超大 PDF 拖死服务
        if upload_file.size > 20 * 1024 * 1024:
            return JsonResponse({"code": 1, "message": "文件不能超过 20MB"}, status=400)

        # 先把上传的文件落到临时目录
        fd, tmp_path = tempfile.mkstemp(suffix=".pdf")
        with os.fdopen(fd, "wb") as dest:
            for chunk in upload_file.chunks():
                dest.write(chunk)

        try:
            content, pages = extract_and_clean_pdf(tmp_path)
        except Exception as exc:
            return JsonResponse({"code": 1, "message": f"解析失败: {exc}"}, status=500)
        finally:
            os.remove(tmp_path)

        return JsonResponse({
            "code": 0,
            "message": "ok",
            "data": {
                "content": content,
                "pages": pages,
                "filename": filename,
            }
        })

这个视图里有一个非常容易被忽视的点：我用了 tempfile.mkstemp 而不是直接把文件存在 MEDIA_ROOT。理由很简单，PDF 解析是一次性行为，中间文件如果还要定期清理，就多了一个运维任务。用临时文件配合 finally 删除，请求结束即清理，最省心。

3.2 CSRF 和跨域问题别硬扛

政务项目里前端地址和后端地址经常不一样，要么是 http://192.168.x.x:8080 访问前端，Django 跑在 8000 端口，要么是前后端分离部署在同一个 Nginx 下但不同 location。这就绕不开 CSRF 和跨域。

我这个演示代码里用了 @csrf_exempt，原因是这个接口本身不是基于 cookie session 的登录态校验，它靠的是登录后的 token 请求头。实际生产环境我建议所有上传类接口都走接口鉴权，比如在请求头上带 Authorization，Django 里自定义一个权限校验装饰器。CSRF 是为浏览器 cookie 场景设计的，纯 token 接口用 csrf_exempt 并不算偷懒，但前提是你真的没有依赖 session cookie 做身份认证。

如果必须支持跨域，不要自己手写一堆 Access-Control-Allow-Origin 响应头来解决问题，直接使用 django-cors-headers 库，然后准确配置 CORS_ALLOWED_ORIGINS。这里有个经验：跨域调试时如果你开了 Chrome 的禁用安全策略，接口能通，一换正常浏览器就报 CORS 错误，这会导致前端以为后端代码有问题，后端排查半天发现根本没有请求到达 Django。所以前后端联调时前端不要用 --disable-web-security 绕过，老老实实把 CORS 配置好。

3.3 解析任务的阻塞和超时问题

PDF 解析不是所有文件都能在几十毫秒内完成。有些扫描件 PDF，单页图片特别大，PyMuPDF 打开的时候还快，但如果你加了 OCR 识别，一页可能要好几秒。一个 200 页的大文件同步解析，Django 同步视图会一直占着 worker，此时其他请求全部排队，如果线上用的是默认的开发服务器甚至 Gunicorn 单 worker，整个系统会表现为“假死”。

我的建议分两层处理：

第一层，接口层限制。文件大小限制到 20MB 以下，同时限制最大页数，比如超过 100 页的 PDF 直接返回“请拆分后上传”。这能挡住绝大多数异常大文件。

第二层，如果你们业务确实需要解析大 PDF，那一定要把解析任务丢到 Celery 后台执行。接口收到文件后先把文件存到本地，然后返回一个 task_id，前端每 2 秒轮询一次任务状态，等后台解析完成后，再通过另一个接口拿解析结果。很多团队一开始图省事用同步实现，等到高峰期某个 100 页文件把请求拖到超时，前端不知道结果、用户疯狂点按钮，后面的请求又堵上来，才会意识到问题。我建议在同步实现里也加上最长 15 秒的硬超时，并做好前端 Loading 状态提示。

还有 Docker 部署时的内存问题。PyMuPDF 解析超大 PDF 时内存上涨明显，如果容器内存限制在 512MB，解析 50MB 以上的文件时很容易被 OOM Kill。所以容器部署时给解析服务单独设置内存上限，或者单独拆一个解析微服务，别让 PDF 解析和核心业务接口挤在同一个进程里。

4. wangEditor 端接入：自定义导入、回填与只读切换

后端接口就绪后，前端要把“选择 PDF → 上传 → 接收文本 → 插入编辑器”这个交互串起来。这里要解释清楚一个常见误区：很多人看到 wangEditor 论坛里有关 customUpload 的帖子，就以为必须用上传图片的那套配置来传 PDF。实际上 wangEditor 的图片上传菜单是给图片用的，如果你强行把 PDF 塞进 customUpload 的回调里，虽然文件能传上去，但编辑器会认为你在插入图片，还会尝试塞一个 <img> 标签，完全没有意义。

4.1 自己做一个“导入 PDF”按钮比扩展菜单省事得多

如果你用的是 wangEditor v5，扩展一个自定义工具栏菜单不是不行，但相关 API 比较复杂，需要注册新的 menu 类型，还要处理图标、active 状态、disabled 状态。在这个需求里，更务实的做法是在编辑器上方放一个独立按钮，配合一个隐藏的 <input type="file">，专门用来接收 PDF 文件。这样既不用改动 wangEditor 内部注册，也方便单独控制按钮样式。

页面结构可以这样写：

html复制<div class="editor-wrapper">
  <div>
    <button type="button" id="btnImportPdf">导入 PDF 并解析</button>
    <input type="file" id="pdfFileInput" accept="application/pdf,.pdf" style="display:none;">
    <button type="button" id="btnToggleReadonly">切换只读</button>
  </div>
  <div id="toolbar-container"></div>
  <div id="editor-container"></div>
</div>

注意这里和“图片菜单”有一个重要区别：accept="application/pdf,.pdf" 只允许选 PDF 文件。有的浏览器在 Mac 上只写 application/pdf 会识别不了，所以我把 .pdf 后缀也加上，保险一点。

初始化 wangEditor v5 的代码是：

javascript复制import { createEditor, createToolbar } from '@wangeditor/editor';

const editor = createEditor({
  selector: '#editor-container',
  html: '<p><br></p>',
  config: {
    placeholder: '请输入公文正文内容...',
  },
  mode: 'default',
});

const toolbar = createToolbar({
  editor,
  selector: '#toolbar-container',
  mode: 'default',
});

4.2 上传 PDF 并解析，拿到文本再回填

接下来是按钮的事件绑定。点击“导入 PDF 并解析”时，触发隐藏的文件框选择文件；文件选择完毕后，直接通过 FormData 上传到我们刚才写的 Django 接口。

我这里直接用的原生 fetch，没有引入 axios。如果项目里已经用了 axios，传 FormData 时有个经典踩坑点：不要手动设置 Content-Type，否则浏览器不会自动帮你生成 multipart/form-data 的 boundary，后端接收到的文件流会异常。原生 fetch 同样不要去手动设置。

javascript复制let uploading = false;

document.getElementById('btnImportPdf').addEventListener('click', () => {
  document.getElementById('pdfFileInput').click();
});

document.getElementById('pdfFileInput').addEventListener('change', async (event) => {
  const file = event.target.files[0];
  if (!file) return;

  if (uploading) {
    alert('正在解析中，请稍候');
    return;
  }

  uploading = true;
  const formData = new FormData();
  formData.append('file', file);

  try {
    const response = await fetch('/api/parse-pdf', {
      method: 'POST',
      body: formData,
      headers: {
        'Authorization': `Bearer ${localStorage.getItem('token')}`
      }
    });
    const result = await response.json();
    if (result.code === 0) {
      const content = result.data.content;
      insertParsedContent(editor, content);
    } else {
      alert(result.message || '解析失败');
    }
  } catch (err) {
    console.error(err);
    alert('网络请求失败，请检查服务是否可用');
  } finally {
    uploading = false;
    // 重要：清掉 input value，保证连续导入同一个文件也能触发 change
    event.target.value = '';
  }
});

这里最后一行 event.target.value = '' 是很容易漏掉的细节。如果你不清空，用户解析完文件 A 后，再次选择同一个文件 A，浏览器不会触发 change 事件，功能就跟“失灵”了一样。很多人在测试时用同一个 PDF 反复试，会以为是上传或解析问题，查半天才发现是这个原因。

4.3 插入编辑区到底用 insertText 还是 dangerouslyInsertHtml

拿到后端返回的纯文本后，回填 wangEditor 有几个选择。最直观的是用 editor.insertText(content)，这个方法会把纯文本插入到当前光标处。但如果后端返回的文本带着多个段落，我用 insertText 插入后所有段落会连成一个不分段的长文本，那显然不是公文的阅读样子。

wangEditor v5 还提供了 editor.dangerouslyInsertHtml(html)，可以做更强力的插入。我的做法是先把后端返回的纯文本按换行符拆分成数组，每行包一层 <p>，再调用 dangerouslyInsertHtml：

javascript复制function textToHtml(text) {
  return text
    .split('\n')
    .map((line) => `<p>${line.trim() || '<br>'}</p>`)
    .join('');
}

function insertParsedContent(editor, content) {
  if (editor.isEmpty()) {
    // 空编辑器直接设置，效果更干净
    editor.setHtml(textToHtml(content));
  } else {
    editor.dangerouslyInsertHtml(textToHtml(content));
  }
}

这里有一个安全性的重要提醒：dangerouslyInsertHtml 方法名字里的 “dangerously” 不是开玩笑的。PDF 解析出的文本虽然看着是从文件里来的，但如果这个 PDF 来源不可信，文件内容里可能带了恶意 HTML。比如一个 PDF 的文字里包含了 <img src=x onerror=alert(1)>，PyMuPDF 解析提取时不会帮你去除这段 HTML 标签，你把它直接插入编辑器就会造成 XSS 漏洞。

安全做法有两种：一种是在后端解析时把文本里的 <、> 等字符做 HTML 实体转义，保证插入的是纯文本；另一种是前端在插入前剥掉所有 HTML 标签。我更推荐后端处理，因为 PDF 解析服务本身是面向多端的，后端统一的清洗规则能保证所有渠道都安全。

4.4 只读模式：切换 key 的正确打开方式

热词里提到的“wangeditor 怎么设置只读”，在这个项目里的应用场景是：导入的 PDF 解析结果刚刚插入编辑器时，用户需要先通读一遍，确认有没有明显乱码或段落错乱，这时候最好先处于只读状态，等确认没问题再点“编辑开启”进行修改。还有一种场景是公文审批时，审批人只能看不能改，但后续要用同一个编辑器归档留痕。

wangEditor v5 提供了非常方便的 API：editor.disable() 和 editor.enable()。注意，不是通过修改某个配置项再调用 updateView 来实现的，它在 v5 里就是两个独立的实例方法。切换代码很简单：

javascript复制let isReadonly = false;
document.getElementById('btnToggleReadonly').addEventListener('click', () => {
  if (isReadonly) {
    editor.enable();
    isReadonly = false;
  } else {
    editor.disable();
    isReadonly = true;
  }
});

这里有一个体验上的坑：editor.disable() 会让整个编辑区域不可输入，但文本选择、鼠标滚轮这些操作应该仍然保留。有些团队为了做只读，给编辑器容器加了 pointer-events: none，这种做法把滚动也禁了，用户看长文时拖都拖不动，体验极差。正确的是始终用 wangEditor 提供的 disable() 方法，不要自己用 CSS 去遮罩编辑区。我还遇到过一个诡异现象：只读状态下，编辑器工具栏的“加粗”“颜色”按钮看起来还亮着，用户点了没反应。这也是 v5 的正常表现，disable() 针对的是编辑区，工具栏样式需要你自己根据状态加 disabled class 来联动，并不是 bug。

如果你还维护着老项目用 wangEditor v4，要提醒一句：v4 想动态切换只读并没有特别顺手的 API，通常需要在创建编辑器前通过 config.readOnly 配置，运行中再切换往往要销毁重建。如果你的项目里有大量这种动态只读场景，升级到 v5 是值得的，付出的迁移成本主要就是 API 命名差异，比如 v4 的 editor.txt.html() 设置或获取完整内容，在 v5 里对应 editor.getHtml() 和 editor.setHtml()。

另外，docx 里常见的“导入 PDF 表格”问题，在处理完文本插入后还可能出现。如果后端识别到表格区域并返回了占位符或者 Markdown 风格的行列文本，前端可以再把这些行转换成 <table>。但我的建议是，第一版先别做表格还原，先把纯文本链路跑通再迭代，否则项目大概率会卡在表格这个深坑里出不来。

5. 常见问题速查与逐条排查

我把这个项目落地过程中被问得最多的几个问题整理成了排查表，每个问题的现象、原因、解决方式直接列出来，方便大家在实际开发时对号入座。

5.1 PDF 解析出来是乱码，先确认有没有文本层

第一优先级永远是判断 PDF 是不是扫描件。很多用户传上来的“PDF 文件”其实是打印机扫描出来的一堆图片，文字根本不存在。你在浏览器里打开 PDF，如果鼠标无法选中任意单词，那基本可以判定没有文本层。对这种文件，PyMuPDF、pdfplumber 都无能为力，接 OCR 才能解决。

政务办公场景里，OCR 的选型我建议优先看中文字库识别率和部署条件。如果你的环境有 GPU 资源，PaddleOCR 是一个不错的选择；如果只是 CPU 服务器，Tesseract 配合中文语言包也能跑，但准确率相对差一些。OCR 是一个独立的子系统，绝对不要把 OCR 和 PDF 解析放在同一个同步请求里，否则等待时间会让你怀疑人生。

5.2 解析顺序乱，检查是不是排版问题

有一次用户导入一份带有两个附件的公文，附件一页是横向表格，附件二是纵向文字。最后解析结果里，横向表格的文字和纵向正文穿插在一起，几乎没法用。排查后发现是那份 PDF 在同一页里混用了两种页面方向，常规的按 y 坐标排序只适合同一方向内容。处理这种混合方向 PDF 时，解析需要先根据页面旋转参数判断该页的坐标系，再选择排序规则。不过遇到这种文件，我的建议还是适当降级：只提取其中一部分，或者直接提示用户该 PDF 版式复杂，推荐手动导入 DOCX 模板。技术方案要解决 80% 的常见场景，剩下 20% 的极端版式靠人工兜底，这是很现实的产品策略。

5.3 回填后编辑器说内容为空？

还有一个非常隐蔽的问题：从后端返回的解析文本可能是一个空字符串，比如扫描件跑 OCR 失败，或者用户传了一个空白 PDF。前端拿到空字符串后会调用 editor.setHtml('')，这在 wangEditor v5 里可能不会正常清空编辑器，甚至后续再插入内容时出现异常。所以接口层面最好有一个明确的约定：如果解析出的有效内容为空，后端直接返回 code: 1 并附带提示“该 PDF 未解析到有效文字”，前端就不用去碰 setHtml 了。所有 UI 交互的异常都尽量在后端给出明确语义，前端只负责展示，这能省掉大量联调时“前端也不知道哪里错了”的问题。

最后给同类项目的一些实际建议

做完了这套导入链路，我最大的体会是：PDF 解析功能的复杂度往往不在于“解析”本身，而在于它背后牵扯的内容清洗、排版还原和异常降级策略。一个能在技术上“提取出文字”的方案，离用户真正满意还差着十万八千里。如果一开始只想着赶紧把 PDF 解析出来回填到 wangEditor，那大概率第一版上线后会收到一堆“顺序不对”“页眉混进来了”“表格乱了”之类的反馈。

以我这次的经验看，有三个环节值得你做第一版时就打好基础。第一个是后端解析一定要保留清晰的“行”结构，这会直接影响前端能否按段落格式回填；第二个是页眉页脚过滤和脏数据清洗要留出可配置的规则，因为不同来源的 PDF 噪声模式不一样，等用户反馈出来再硬编码规则会非常被动；第三个是提前和产品约定好哪些场景不支持，比如扫描件 OCR、复杂表格还原，与其让用户抱有不切实际的期待，不如在界面上明确提示“当前仅支持文本型 PDF 的自动导入”，这样技术边界清晰，项目验收也顺畅。