关键词: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。
二、核心功能
| 输入格式 | 输出格式 | 说明 |
|---|---|---|
| .docx | 提取并自动排版,A4 页面 | |
| .docx | TXT | 提取纯文本 |
| .docx | HTML | 带样式 HTML |
| .html/.htm | 无头 Chromium 渲染导出 | |
| .md/.markdown | Markdown 先转 HTML 再渲染 PDF | |
| .md/.markdown | TXT | 去除 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 队列,限制最大并发数 |
| 页面外部资源导致 SSRF | Chromium 禁用 JS,page.route 拦截全部非 data: 请求 |
| 中文文件名乱码 | latin1 还原为 UTF-8,响应头使用 filename*=UTF-8'' |
| 文件不应落盘泄露 | multer 内存存储,转换完即释放,不写入磁盘,不持久化 |
八、总结
本文介绍了 Toolion DocConv 文档格式转换服务的技术实现。核心设计思路:
- 统一转换入口:DOCX / HTML / Markdown 互转,输出 PDF / 纯文本 / HTML,通过转换矩阵声明支持组合;
- 多引擎协作:mammoth 处理 DOCX,marked 处理 Markdown,无头 Chromium 渲染 HTML 为 PDF;
- 内存处理:multer 内存存储,Buffer 全程在内存流转,转换完即释放,文件不落盘;
- 安全防护:Chromium 禁用 JS + 拦截非 data: 请求防 SSRF,渲染槽位限制并发,multer 限制文件大小;
- 文件名兼容:latin1 → UTF-8 还原 + RFC 5987 编码,兼容中文文件名下载;
- 可观测性:
X-Conversion-Time响应头暴露服务端转换耗时。
该方案适合需要轻量级、可扩展文档格式转换能力的后端服务场景,可作为 Node.js + Express 类文档处理服务的参考实现。
#文档转换 #DOCX转PDF #Markdown转PDF #HTML转PDF #Express #TypeScript #mammoth #marked #无头Chromium #SSRF防护 #文档处理 #Node.js #后端开发 #API设计