基于 Express + 无头 Chromium 的文档格式转换服务 DocConv 技术实现

0 阅读8分钟

关键词:DOCX、Markdown、HTML、PDF、文档转换、mammoth、marked、无头 Chromium、SSRF 防护、Express、TypeScript


一、背景与需求

日常办公中,文档格式转换是高频需求:合同、报告、简历需要转成 PDF 固定排版;技术笔记需要从 Markdown 转成 PDF 归档;网页内容需要导出为 PDF 离线阅读;有时只需要提取纯文本方便二次编辑。

现有的在线转换工具普遍存在以下问题:

  • 文件需上传到第三方服务器,合同、简历、财务报表等敏感文档泄露风险高;
  • 多数工具加水印、限制转换次数、或要求注册登录 / 安装桌面客户端;
  • 不同格式的转换组合零散,缺乏统一的 DOCX / MD / HTML 互转方案。

基于此,我在 Toolion 平台上开发了 DocConv 文档格式转换服务(项目地址:toolion.cn/docconv/),提… DOCX、HTML、Markdown 之间的互转,输出为 PDF、纯文本或带排版的 HTML。 在这里插入图片描述


二、核心功能

输入格式输出格式说明
.docxPDF提取并自动排版,A4 页面
.docxTXT提取纯文本
.docxHTML带样式 HTML
.html/.htmPDF无头 Chromium 渲染导出
.md/.markdownPDFMarkdown 先转 HTML 再渲染 PDF
.md/.markdownTXT去除 Markdown 语法,提取纯文本

其他特性:

  • 单文件最大 10MB,覆盖绝大多数日常办公文档;
  • 转换耗时通过 X-Conversion-Time 响应头返回;
  • 输出文件名保留原文件名,仅更换后缀;
  • 提供 GET /api/docconv/formats 查询支持的格式组合;
  • 提供 POST /api/docconv/extract-text 专门提取 docx/md 的纯文本,返回 JSON。

三、整体架构

DocConv 是前后端分离的 Web 服务:

┌─────────────┐      HTTP (multipart/form-data)      ┌──────────────────┐
│  前端页面   │ ───────────────────────────────────▶ │  Express 后端    │
│ (public/)   │  file + format                       │  /api/docconv    │
└─────────────┘                                      │  (routes + ctrl) │
                                                     └────────┬─────────┘
                                                              │
                          ┌─────────────────────────────────┘
                          │
                          ▼
                 ┌──────────────────┐
                 │  docconv service │
                 │  (src/services/) │
                 │  • mammoth       │  docx → html / text
                 │  • marked        │  md   → html / text
                 │  • headless      │  html → PDF (Chromium)
                 │    Chromium      │
                 └──────────────────┘

前端负责文件选择、格式选择、进度提示和结果下载;后端负责文件格式校验、转换执行、PDF 渲染及安全防护。


四、后端实现细节

4.1 路由与中间件

使用 Express Router + multer 内存存储,文件不落盘,直接在内存缓冲区处理,转换完即释放:

// src/routes/docconv.ts
import { Router } from 'express';
import multer from 'multer';
import { config } from '../config';
import { generalLimiter } from '../middleware';
import { convertFile, extractText, getFormats } from '../controllers/docconv.controller';

const upload = multer({
  storage: multer.memoryStorage(),
  limits: { fileSize: config.DOCCONV_MAX_FILE_SIZE }, // 10MB
});

const apiRouter = Router();

apiRouter.get('/formats', generalLimiter, getFormats);
apiRouter.post('/convert', generalLimiter, upload.single('file'), convertFile);
apiRouter.post('/extract-text', generalLimiter, upload.single('file'), extractText);

export { apiRouter };
  • multer.memoryStorage():文件仅驻留内存,避免磁盘残留;
  • fileSize 限制:防止超大文件耗尽服务器资源;
  • generalLimiter:接口限流,防止暴力请求。

4.2 控制层:请求校验与文件名处理

控制器负责参数校验、源格式探测、调用服务层转换、设置响应头并返回二进制流:

// src/controllers/docconv.controller.ts (节选)
const SOURCE_FORMATS: SourceFormat[] = ['docx', 'html', 'md'];
const TARGET_FORMATS: TargetFormat[] = ['pdf', 'text', 'html'];

function detectSource(originalName: string): SourceFormat | null {
  const lower = (originalName || '').toLowerCase();
  const dot = lower.lastIndexOf('.');
  const ext = dot === -1 ? '' : lower.slice(dot + 1);
  if (ext === 'docx') return 'docx';
  if (ext === 'html' || ext === 'htm') return 'html';
  if (ext === 'md' || ext === 'markdown') return 'md';
  return null;
}

// multer/busboy 会将非 ASCII 文件名按 latin1 解码,需还原为 UTF-8
function fixLatin1Filename(name: string): string {
  try {
    return Buffer.from(name, 'latin1').toString('utf-8');
  } catch {
    return name;
  }
}

export async function convertFile(req, res, next) {
  // ... 校验 req.file、source、target ...
  const result = await convert(req.file.buffer, source, target);
  const elapsed = Date.now() - start;
  const filename = `${baseName(req.file.originalname)}.${result.ext}`;
  res.setHeader('Content-Type', result.contentType);
  res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`);
  res.setHeader('X-Conversion-Time', `${elapsed}ms`);
  res.send(result.buffer);
}

关键点:

  • 文件名编码修复:multer/busboy 在部分客户端下会把非 ASCII 文件名按 latin1 解码,通过 Buffer.from(name, 'latin1').toString('utf-8') 还原,避免中文文件名乱码;
  • filename*=UTF-8'':RFC 5987 编码方式,兼容各类浏览器下载中文文件名;
  • X-Conversion-Time:返回服务端转换耗时,便于前端展示和性能排查;
  • 转换超时(如 Chromium 渲染卡死)返回 504,其它错误走统一错误中间件。

4.3 服务层:三种格式的转换链路

服务层封装所有转换逻辑,完全在内存中操作 Buffer,不落盘:

// 转换矩阵
export const CONVERSIONS: Record<SourceFormat, TargetFormat[]> = {
  docx: ['pdf', 'text', 'html'],
  html: ['pdf'],
  md: ['pdf', 'text'],
};

DOCX → HTML / Text

使用 mammoth 解析 .docx:

async function docxToHtml(input: Buffer): Promise<string> {
  const result = await mammoth.convertToHtml({ buffer: input });
  return wrapWithLayout(result.value);
}

async function docxToText(input: Buffer): Promise<string> {
  const result = await mammoth.extractRawText({ buffer: input });
  return result.value;
}

Markdown → HTML / Text

使用 marked(GFM 模式,支持换行)将 Markdown 解析为 HTML,文本输出则进一步剥离标签:

function mdToHtml(input: Buffer): string {
  marked.setOptions({ gfm: true, breaks: true });
  const body = marked.parse(input.toString('utf-8')) as string;
  return wrapWithLayout(body);
}

function mdToText(input: Buffer): string {
  const html = marked.parse(input.toString('utf-8')) as string;
  return htmlToText(html); // 正则剥离标签并解码实体
}

HTML → PDF(无头 Chromium)

这是最复杂的环节。使用 getBrowser() 获取复用的 Chromium 浏览器实例,在无上下文(incognito context)中渲染:

async function htmlToPdf(htmlContent: string): Promise<Buffer> {
  let html = htmlContent;
  if (html.indexOf('<html') === -1) {
    html = wrapWithLayout(html); // 统一包裹 A4 排版样式
  }

  await acquireRenderSlot();       // 并发数控制
  const browser = await getBrowser();
  const ctx = await browser.newContext({ javaScriptEnabled: false });
  try {
    const page = await ctx.newPage();

    // SSRF 防护:拦截全部非 data: 请求,禁止页面加载外部图片、iframe、链接
    await page.route('**/*', (route) => {
      if (route.request().url().startsWith('data:')) {
        route.continue();
      } else {
        route.abort();
      }
    });

    await page.setContent(html, {
      waitUntil: 'load',
      timeout: config.DOCCONV_PDF_TIMEOUT,
    });

    const pdf = await page.pdf({
      format: 'A4',
      margin: { top: '20mm', bottom: '20mm', left: '18mm', right: '18mm' },
      printBackground: true,
      preferCSSPageSize: true,
    });
    return pdf as Buffer;
  } finally {
    await ctx.close();
    releaseRenderSlot();
  }
}

并发渲染槽位控制

Chromium 渲染 PDF 占用内存和 CPU 较高,通过计数器 + 队列限制并发数,避免请求突发导致资源耗尽:

let activeRenders = 0;
const renderQueue: Array<() => void> = [];

async function acquireRenderSlot(): Promise<void> {
  if (activeRenders < config.DOCCONV_CONCURRENCY) {
    activeRenders++;
    return;
  }
  await new Promise<void>((resolve) => renderQueue.push(resolve));
  activeRenders++;
}

function releaseRenderSlot(): void {
  activeRenders--;
  const next = renderQueue.shift();
  if (next) next();
}

A4 文档排版模板

所有 HTML → PDF 输出统一套用文档优化的 A4 布局(中文字体、行距、标题样式、分页控制):

@page { size: A4; margin: 20mm 18mm 20mm 18mm; }
body { font-family: "Microsoft YaHei", "PingFang SC", "Noto Sans CJK SC", "SimSun"; font-size: 14px; line-height: 1.6; }
h2, h3 { page-break-after: avoid; }
p, li, table { page-break-inside: avoid; }

4.4 安全防护

风险点防护措施
SSRF(服务端请求伪造)Chromium 禁用 JavaScript,并拦截全部非 data: 协议的网络请求,页面无法向内网或外网发起请求
并发资源耗尽渲染槽位计数器 + 等待队列,限制最大并发 Chromium 页数
超大文件攻击multer fileSize 限制(10MB),超限直接拒绝
转换超时page.setContent 与 page.pdf 带超时配置,超时返回 504
中文文件名乱码latin1 → utf8 还原 + RFC 5987 filename*=UTF-8'' 编码
内存残留multer 内存存储 + 响应发送后 Buffer 自动释放,文件不落盘不持久化

五、前端调用示例

前端页面 public/docconv/index.html 使用原生 fetch 上传文件,收到二进制流后创建本地 URL 触发浏览器下载:

var fd = new FormData();
fd.append('file', state.file);
fd.append('format', state.format); // pdf | text | html

fetch('/api/docconv/convert', {
  method: 'POST',
  body: fd,
  credentials: 'include',
})
  .then(function (res) {
    if (!res.ok) {
      return res.json().catch(function () { return {}; }).then(function (j) {
        throw new Error(j.message || '转换失败');
      });
    }
    var disposition = res.headers.get('Content-Disposition');
    return res.blob().then(function (blob) {
      var name = parseFilename(disposition, base + '.pdf');
      var url = URL.createObjectURL(blob);
      var a = document.createElement('a');
      a.href = url;
      a.download = name;
      document.body.appendChild(a);
      a.click();
      document.body.removeChild(a);
      URL.revokeObjectURL(url);
    });
  })
  .catch(function (err) {
    setStatus(err.message, 'error');
  });

前端还会读取 X-Conversion-Time 响应头,在提示中展示服务端转换耗时。


六、使用示例

示例:将一份 合同.docx 转为 PDF

curl -X POST https://toolion.cn/api/docconv/convert \
  -F "file=@合同.docx" \
  -F "format=pdf" \
  -o 合同.pdf

响应头包含:

Content-Type: application/pdf
Content-Disposition: attachment; filename*=UTF-8''%E5%90%88%E5%90%8C.pdf
X-Conversion-Time: 842ms

示例:查询支持的格式

curl https://toolion.cn/api/docconv/formats

返回:

{
  "code": 0,
  "data": {
    "formats": {
      "docx": ["pdf", "text", "html"],
      "html": ["pdf"],
      "md": ["pdf", "text"]
    },
    "sources": ["docx", "html", "md"]
  }
}

七、关键技术挑战与解决方案

挑战解决方案
多格式统一转换入口按源格式分发到 mammoth / marked / Chromium 三条链路,通过 CONVERSIONS 矩阵声明支持组合
HTML 渲染 PDF 需稳定排版统一包裹 A4 CSS 布局模板,控制字体、行距、标题分页行为
Chromium 并发渲染耗尽资源渲染槽位计数器 + FIFO 队列,限制最大并发数
页面外部资源导致 SSRFChromium 禁用 JS,page.route 拦截全部非 data: 请求
中文文件名乱码latin1 还原为 UTF-8,响应头使用 filename*=UTF-8''
文件不应落盘泄露multer 内存存储,转换完即释放,不写入磁盘,不持久化

八、总结

本文介绍了 Toolion DocConv 文档格式转换服务的技术实现。核心设计思路:

  1. 统一转换入口:DOCX / HTML / Markdown 互转,输出 PDF / 纯文本 / HTML,通过转换矩阵声明支持组合;
  2. 多引擎协作:mammoth 处理 DOCX,marked 处理 Markdown,无头 Chromium 渲染 HTML 为 PDF;
  3. 内存处理:multer 内存存储,Buffer 全程在内存流转,转换完即释放,文件不落盘;
  4. 安全防护:Chromium 禁用 JS + 拦截非 data: 请求防 SSRF,渲染槽位限制并发,multer 限制文件大小;
  5. 文件名兼容:latin1 → UTF-8 还原 + RFC 5987 编码,兼容中文文件名下载;
  6. 可观测性:X-Conversion-Time 响应头暴露服务端转换耗时。

该方案适合需要轻量级、可扩展文档格式转换能力的后端服务场景,可作为 Node.js + Express 类文档处理服务的参考实现。


#文档转换 #DOCX转PDF #Markdown转PDF #HTML转PDF #Express #TypeScript #mammoth #marked #无头Chromium #SSRF防护 #文档处理 #Node.js #后端开发 #API设计