3分钟上手 ReLaXed:从零安装到生成第一份专业 PDF 完整教程
3分钟上手 ReLaXed:从零安装到生成第一份专业 PDF 完整教程
ReLaXed 是一款开源的 PDF 生成工具,让你用网页技术(Pug、SCSS、Markdown、CSS)交互式地创建专业 PDF 文档。本文是一份面向新手的 ReLaXed 安装与使用完整教程:只需 3 分钟,从 ReLaXed 安装到生成第一份 PDF,全程只需几条命令,保存文件后 PDF 还会自动实时更新。🚀
为什么选择 ReLaXed:用网页技术做 PDF
如果你喜欢用 Markdown 或 LaTeX 这类标记语言写文档,但又被它们的限制困扰——Markdown 排版能力弱、LaTeX 语法晦涩——ReLaXed 给出了第三条路:把现代网页技术带进 PDF 创作。
- 🎨 用 CSS 框架和 SCSS 打造干净现代的版式
- 📈 内置 图表、流程图、公式 渲染(Vega-Lite、Mermaid、MathJax/KaTeX)
- ⚡ 文件一保存,PDF 自动重新生成,所见即所得
- 🧩 支持 插件机制,可扩展任意 JavaScript/CSS 库
ReLaXed 的工作原理很直观:Pug 编译为 HTML、SCSS 编译为 CSS,再由无头 Chromium 打印成 PDF。整个技术栈如下图:
第一步:一条命令安装 ReLaXed
ReLaXed 基于 Node.js 生态,请确保系统已安装 Node.js(建议 18 以上版本)。然后打开终端,执行:
npm i -g relaxedjs
注意:不要使用 sudo 安装。
安装成功后,系统会获得 relaxed 命令,这就是 ReLaXed 的命令行入口(实现在 src/index.js)。
第二步:创建你的第一个 Pug 文档
在当前目录新建文件 my_document.pug,写入两行 Pug 代码(Pug 是 HTML 的简洁写法,类似 Markdown 的轻松感):
h1 My document's title
p A paragraph in my document
完整的最小示例可以参考项目自带的 test/samples/pug/basic_example/master.pug,它还演示了如何用内联 style 设置字体大小和对齐方式。
第三步:一行命令生成你的第一份 PDF
在终端运行:
relaxed my_document.pug
ReLaXed 会立即生成 my_document.pdf,并持续监听该目录:之后每次修改源文件,PDF 都会自动重新构建——这就是 ReLaXed "交互式" 的精髓 ✨。如果只需生成一次(比如用于自动化脚本),加上 --build-once 参数即可:
relaxed my_document.pug --build-once
下面就是用 basic_example 模板生成的 PDF 效果(大标题 + 自定义样式):
ReLaXed 进阶技巧:让 PDF 更专业的 4 种方法
1️⃣ 混用 Markdown 与 SCSS 排版
Pug 文档里可以直接嵌入 Markdown 内容块和 SCSS 样式,写一封信只需一个 master.pug 加一个 letter.scss,完整源码见 test/samples/pug/letter/master.pug:
2️⃣ 用 KaTeX 排版数学公式
在文档目录放一个 config.yml 启用插件即可(参考 test/samples/pug/katex/config.yml):
plugins:
- katex
生成的 PDF 中公式渲染效果如下:
3️⃣ 为每页添加页眉页脚和页码
用 template#page-footer / template#page-header 定义页脚页眉,#[span.pageNumber] 会自动显示当前页码,效果如下:
4️⃣ 启用内置图表插件
ReLaXed 默认加载了一组零开销插件:表格 CSV 转换、Chart.js 图表、Vega-Lite 绘图、流程图、Mermaid 图表、SCSS 和 Markdown(清单见 src/builtin_plugins/index.js)。需要 MathJax、KaTeX 这类可选插件时,在 config.yml 里声明即可,插件加载逻辑位于 src/plugins.js。
常用命令参数速查
| 参数 | 作用 |
|---|---|
relaxed 目录 |
自动探测目录中的 master.pug 作为主文件 |
--bo / --build-once |
只构建一次,不监听变化 |
-l, --locals <json> |
传入 JSON 变量供 Pug 渲染 |
--no-sandbox |
在无沙箱环境(如容器)中禁用 Puppeteer 沙箱 |
参数的完整定义见 src/index.js。
接下来去哪里探索
- 📄 核心渲染逻辑:src/masterToPDF.js —— Pug/SCSS 到 PDF 的转换入口,也可作为 Node 模块调用
- 🧪 更多实战样本:test/samples/interactive_example/master.pug(侧边栏、表格、图文混排)
- 📜 版本更新记录:changelog.md
- 🖼️ 技术架构图源文件:docs/relaxed_stack.png
现在就安装 ReLaXed、写下第一行 Pug,3 分钟后你会得到第一份属于自己的专业 PDF 文档 🎉




