# Markdown PDF 导出器进度

最后更新：2026-07-26

## 1. 当前概况

项目目录：

```text
C:\Projects\md-to-pdf
```

当前分支：

```text
main
```

已有提交：

```text
d1b5880 feat: 实现 Chromium PDF 导出与精确预览
d625523 fix: 修复长文档分页与滚动同步
1d93f31 feat: 实现真实分页预览
52cf816 feat: 完善导出设置与打印预览
ec14f79 feat: 扩展本地主题兼容能力
fa07472 feat: 实现网页实时预览
7224dfd feat: 实现 Markdown 渲染核心
ec48bce chore: 初始化项目骨架
```

最新阶段已完成 Mermaid 全局导出配置、ELK 布局、代码块配置覆盖、重绘隐藏和两种预览模式共用的显示缩放。

## 2. 已完成

### 2.1 项目骨架

- 建立 npm workspaces。
- 建立 React + Vite 前端。
- 建立 Fastify 后端。
- 建立 `packages/core` 共享包。
- 建立主题、测试和 Docker 目录。
- 初始化本地 Git 仓库。

### 2.2 导出配置模型

`packages/core/src/export-config.ts` 已包含：

- 版本 3 配置模型；
- A3、A4、A5、Letter、Legal、Tabloid 和自定义纸张；
- 横向、纵向；
- 四边页边距；
- 页眉和页脚左右中区域；
- 页码位置和格式；
- PDF 元数据；
- 打印背景、缩放和一级标题分页选项；
- Mermaid 布局、主题、外观和字体；
- Zod 数据校验；
- 默认 A4 技术文档预设。

### 2.3 主题接口

`packages/core/src/theme.ts`、`themes/typora-like` 和动态主题注册器已包含：

- 版本化主题清单；
- 主题 ID、名称、版本、作者、许可证；
- DOM 预设；
- 支持能力声明；
- 可选基础 CSS、主体 CSS 和打印 CSS；
- 自制 Typora 风格主题；
- `#write` 兼容文档结构；
- 内置主题和 `.local/themes` 本地主题动态扫描；
- 按基础 CSS、主体 CSS、打印 CSS 的固定顺序组合；
- 主题内相对 CSS `@import` 安全展开；
- 主题 CSS 相对资源重写与受限资源接口；
- 目录匹配、真实路径包含关系和外部 URL 安全检查。

内置主题为项目自有实现，没有复制 Typora 官方默认主题。用户可以通过导入工具将本机已安装的 Typora 基础 CSS以及 GitHub、Pixyll 和 Whitey 三套适合打印的白色默认主题复制到 Git 忽略的 `.local/themes`。这些副本仅供本机使用，不进入仓库、容器或发布包。

### 2.4 Markdown 渲染核心

提交 `7224dfd` 已完成：

- `packages/renderer` 独立工作区；
- Front Matter 解析；
- Markdown 到安全 HTML；
- 标题锚点；
- 表格；
- 任务列表；
- 脚注；
- highlight.js 代码高亮；
- KaTeX 数学公式；
- Mermaid 安全占位；
- sanitize-html 安全过滤；
- 元数据规范化；
- 功能检测；
- 统一 `<article id="write">` 输出；
- 5 项渲染单元测试。

### 2.5 网页实时预览

提交 `fa07472` 已完成：

- 可测试的 Fastify `buildApp()`；
- `POST /api/render` 服务端统一 Markdown 渲染；
- 动态主题清单、CSS 和资源 API；
- Markdown 编辑及本地 `.md` 文件读取；
- 250ms 防抖 A4 实时预览；
- iframe 隔离主题 CSS；
- KaTeX、highlight.js 和按需加载的 Mermaid；
- 桌面双栏与移动端上下布局；
- 5 项渲染器测试和 4 项后端测试。

### 2.6 主题兼容增强

提交 `ec14f79` 已完成：

- 主题清单可选基础 CSS；
- 基础 CSS、主体 CSS、打印 CSS 固定组合顺序；
- 安全的相对 CSS `@import` 展开和资源 URL 重写；
- CSS 导入深度、循环、外部 URL 和越界路径检查；
- GitHub、Pixyll 和 Whitey 三套本地 Typora 白色主题导入；
- 可恢复替换和默认防覆盖；
- 主题开发指南；
- 后端测试增至 6 项。

### 2.7 导出设置与打印预览

提交 `52cf816` 已完成：

- 导出配置升级到版本 3，并兼容迁移版本 2 浏览器缓存；
- 纸张收敛为 A3、A4、A5、US-Letter 和 US-Legal；
- 默认 A4 纵向和 16mm 四边页边距；
- 统一 96 CSS px/in、72 PDF pt/in 和 25.4mm/in 的物理单位换算；
- 响应式导出设置抽屉；
- 纸张、方向、页边距、页眉、页码和主题的版本化浏览器缓存；
- 页眉左中右内容和变量；
- 五种页码样式、对齐和起始页码；
- Mermaid 官方配置 frontmatter、默认主题与错误隔离；
- Mermaid 全局 Dagre/ELK 布局、官方主题、外观和字体设置；
- Markdown 表格对齐属性保留和自适应列宽；
- 纸张尺寸和页边距实时预览。

## 3. Chromium PDF 导出与精确预览

### 3.1 Chromium PDF 导出

- 引入固定版本 Playwright Chromium。
- 新增 `POST /api/pdf`，复用服务端 Markdown 渲染结果、`#write` DOM、主题 CSS、打印 CSS 和统一分页运行时。
- PDF 文本可搜索，支持中文、长表格、KaTeX、Mermaid、页眉、页脚和页码。
- Chromium 浏览器实例复用，每个请求使用独立 BrowserContext。
- 支持浏览器预热、并发门控、排队上限、超时和关闭清理。
- 仅允许同源、`data:`、`blob:` 和 `about:` 资源，阻止 PDF 页面访问外部网络。
- PDF 响应提供安全的 UTF-8 文件名、页数、Mermaid 错误数和 `Server-Timing`。
- 前端“导出 PDF”按钮已启用，生成完成后直接下载。

### 3.2 快速预览与精确预览

- 快速预览继续使用 Paged.js，适合编辑时即时反馈。
- 精确预览直接复用 `/api/pdf` 结果，确保显示页数和最终下载一致。
- 快速与精确模式可以切换，PDF 缓存按 Markdown、主题和导出配置失效。
- PDF.js 使用集中渲染队列，当前可见页优先，滚动方向上的相邻页次优先。
- 远离视口的 Canvas 延迟释放，避免 65 页长文档持续占用大尺寸位图内存。
- 未完成渲染的页面显示白色占位，Canvas 完成后才显示，消除快速滚动时的黑影。
- 编辑区和两种预览模式支持按滚动比例同步定位。

### 3.3 Mermaid 分页性能优化

- Mermaid 仍使用官方渲染器、配置 frontmatter、严格安全模式、默认主题和 classic 样式。
- 渲染完成后记录 SVG 与容器的实际小数宽高，将 SVG 转为内嵌 Data URL 图片再交给 Paged.js 分页。
- 静态 SVG 仍由 Chromium 以矢量和可搜索文字输出，不发生位图化。
- 快速预览和 PDF 默认使用相同的静态 SVG；`mermaid-output=inline-svg` 仅保留为内部诊断开关。
- 65 页、67 个 Mermaid 的附件中，分页耗时约从 2.60 秒降至 1.29 秒，总生成耗时约降低 12.7%。
- A/B PDF 均为 65 页，逐页 61,102 个非空白字符和 11,762 个文本项完全一致。

### 3.4 PDF 性能观测

- 记录排队、浏览器、上下文、导航、文档渲染、Mermaid、资源等待、分页、PDF 打印和总耗时。
- `Server-Timing` 已暴露上述关键阶段，包括 `mermaid-conversion`。
- 65 页附件的主要耗时来自 Mermaid 渲染、Paged.js 分页和 Chromium PDF 打印。
- PDF 缓冲区直接返回，避免无意义的二次 `Buffer` 复制。

### 3.5 AIO 容器部署

- 使用多阶段 Dockerfile 构建前端、后端和共享包。
- 基于 Node.js 22 Debian 构建运行镜像，并由项目锁定的 Playwright
  `1.62.0` 安装精确匹配的 Chromium 与系统依赖。
- 单容器内由 Nginx 提供前端并代理 Fastify API。
- Playwright 通过同一 Nginx 地址加载精确预览运行时。
- 容器以非 root `pwuser` 运行并提供 1 GiB 共享内存。
- Compose 支持端口、只读主题目录、PDF 并发、队列和超时配置。
- 增加容器健康检查和统一进程退出处理。
- Nginx 显式以 JavaScript MIME 类型提供 PDF.js `.mjs` Worker。

### 3.6 Mermaid 配置与预览缩放

- Mermaid 固定为 `11.16.0`，ELK 使用官方
  `@mermaid-js/layout-elk@0.2.2` 并按需加载核心布局代码。
- 全局导出设置支持 Dagre、ELK、官方主题、Classic、Hand-drawn、Neo
  外观和自定义本地字体。
- 单图 `config` Front Matter 可以覆盖全局布局、主题、外观、字体、
  `themeVariables` 和图表专属配置。
- `style`、`classDef` 和 `linkStyle` 保持 Mermaid 原生语义。
- `themeCSS`、严格安全模式和资源限制不能由 Markdown 覆盖。
- Mermaid 与 Paged.js 计算期间隐藏分页 iframe，避免显示官方渲染器的
  临时测量节点。
- 快速预览和精确预览共用 50%～400% 显示缩放，支持滑块、手动输入、
  100% 重置和独立浏览器缓存。
- 缩放不进入导出配置，不改变分页或 PDF；精确预览会按显示宽度重绘
  邻近 Canvas，保持文字清晰。

## 4. 已执行验证

2026-07-26 在当前完整工作区成功执行：

```text
npm test
npm run typecheck
npm run build
git diff --check
```

结果：

- 共享配置测试：8 项通过；
- 渲染器测试：7 项通过；
- 前端测试：55 项通过；
- 后端测试：23 项通过；
- 全项目类型检查通过；
- 生产构建通过；
- `git diff --check` 通过。

已使用浏览器插件完成视觉验证：

- 预览缩放在 50%、100%、150% 和 400% 下均按比例显示，快速与精确
  预览的分页结果不受缩放影响；
- 包含 ELK、Base 主题、Hand-drawn 外观、自定义字体、
  `themeVariables`、`style` 和 `classDef` 的 Mermaid 样例在快速预览
  与精确预览中均成功渲染；
- 65 页附件的快速预览生成 64 页，67 个 Mermaid 全部使用静态 SVG；
- 同一附件的精确预览和最终 PDF 均为 65 页；
- 精确预览快速跳转至第 46、47、65 页，无黑色 Canvas、空白页或渲染错误；
- PDF.js 同时只保留视口邻近页面的 Canvas，远端页面资源可以释放；
- Mermaid A/B PDF 页数、逐页文字和抽样视觉结果一致；
- 抽查第 2、6、27、53、65 页，Mermaid 尺寸、分页位置和末页内容正常。

此前主题阶段已使用浏览器插件完成视觉验证：

- 导入并打开 `tmp/数据中台项目周报_2026_W30.md`；
- 参考 `tmp/数据中台项目周报_2026_W30.pdf` 的 Typora 输出；
- GitHub、Pixyll 和 Whitey 三套保留的本地主题均可正常切换；
- 三套主题中的表格均为 `border-collapse: collapse`、单元格间距为 0，并铺满 `#write` 内容宽度；
- GitHub 表格边框颜色与主题定义的 `#dfe2e5` 一致；
- Open Sans、PT Serif 和 Merriweather 字体资源均成功加载；
- KaTeX、代码高亮和 Mermaid 正常显示；
- 浏览器控制台无警告或错误。

2026-07-26 已在 Docker Desktop 完成 AIO 容器验证：

- Docker Compose 配置展开、镜像构建、启动、健康检查和重启恢复通过；
- 运行镜像约 611 MB，Node.js、Nginx、Fastify 和 Chromium 均以非
  root UID 999 运行；
- Nginx 首页、分页运行页、API、主题 CSS 和 PDF.js Worker 均正常；
- 默认只读挂载识别 1 个内置主题和 3 个本地主题；
- 周报通过容器导出为 4 页，附件通过容器导出为 65 页，Mermaid
  错误数均为 0；
- 两份 PDF 的所有页面均包含可搜索文字，附件共提取 68,434 个字符；
- 抽查周报第 1、4 页和附件第 1、33、65 页，未发现裁切、重叠、
  黑块或空白页；
- 浏览器快速预览、主题切换、精确 PDF.js 预览和导出交互通过；
- 修复 Nginx 缺少 `.mjs` MIME 映射导致精确预览 Worker 加载失败的问题。

为方便用户继续检查，AIO 容器当前运行在 `http://localhost:8080`。

## 5. 当前注意事项

- `output/` 可能包含本地 PDF 验证产物，已被 Git 忽略，不得提交。
- `apps/web/src/App.tsx` 负责分页 iframe 生命周期和父页面消息处理。
- `apps/web/src/paged-document-runtime.ts` 是快速预览和 PDF 共用的 Mermaid、资源等待和 Paged.js 分页运行时。
- `apps/web/src/paged-preview-frame.ts` 负责 iframe 消息协议和运行目标选择。
- `apps/web/src/paged-preview.ts` 负责分页协议、共享文档 CSS、页眉和页码 CSS。
- `apps/web/src/mermaid-page-fit.ts` 负责超高 Mermaid 的单页等比例适配。
- `apps/web/src/mermaid-static-image.ts` 负责锁定 Mermaid 盒模型并转换为静态矢量 SVG 图片。
- `apps/web/src/paged-table-handler.ts` 负责跨页表格表头处理。
- `apps/web/src/PrecisePdfPreview.tsx` 和 `pdf-render-queue.ts` 负责 PDF.js 精确预览和 Canvas 生命周期。
- `apps/web/src/preview-zoom.ts` 和 `PreviewZoomControl.tsx` 负责预览缩放缓存、边界和控制界面。
- `apps/server/src/pdf-engine.ts` 负责 Chromium 生命周期、并发、网络限制、分页调用和 PDF 输出。
- `apps/web/src/ExportSettingsDrawer.tsx` 是导出设置界面。
- `apps/web/src/export-settings.ts` 负责版本化浏览器缓存。
- `packages/core/src/export-config.ts` 是纸张、页边距、页眉页脚和页码的共享模型。
- `apps/server/src/app.ts` 是新增的可测试 Fastify 应用。
- `apps/server/src/theme-registry.ts` 负责内置和本地主题发现、CSS 处理及资源安全。
- `.local/themes/typora-*` 是用户本机副本，已被 Git 忽略，不得提交。
- `.local/theme-backups` 中保留 GitHub、Pixyll 和 Whitey 的可恢复备份；Newsprint 和 Night 的当前副本及备份已按用户要求删除。
- Typora 官方资源是 All Rights Reserved，仅限当前用户本机使用，不进入 Git、容器或发布包。
- 资源目录上传、本地相对图片、临时目录和路径安全尚未实现。
- AIO 容器已经通过 Docker Desktop 构建、端到端和浏览器验证。

## 6. 推荐接手顺序

### 阶段一：资源与安全

- Markdown 文件夹或 ZIP；
- 相对图片解析；
- 每请求独立临时目录；
- 路径穿越和符号链接越界防护；
- 文件数量、单文件大小、总大小和超时限制；
- 请求结束可靠清理。

### 阶段二：导出配置扩展

- Front Matter 元数据覆盖；
- 浏览器本地配置预设；
- 配置 JSON 导入和导出。

## 7. 首版验收目标

- 可以选择或粘贴 Markdown；
- 网页正确预览常用 Markdown、公式和 Mermaid；
- 可以下载真实 PDF；
- PDF 文本可搜索；
- 预览与 PDF 基本一致；
- 支持 A4、Letter、方向和边距；
- 支持基础页眉、页脚和页码；
- 支持主题切换扩展；
- 相对图片可用；
- 转换后不保留用户文档；
- Docker Compose 可在内网启动。