3分钟上手 ReLaXed:从零安装到生成第一份专业 PDF 完整教程

原创2026-09-21 21:41:341,941 阅读
文章标签:开发工具

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 工作原理:从源文件到 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 示例效果:大标题 Hello 页面

ReLaXed 进阶技巧:让 PDF 更专业的 4 种方法

1️⃣ 混用 Markdown 与 SCSS 排版

Pug 文档里可以直接嵌入 Markdown 内容块和 SCSS 样式,写一封信只需一个 master.pug 加一个 letter.scss,完整源码见 test/samples/pug/letter/master.pug:

ReLaXed 排版效果示例:带 Logo、署名和 Markdown 正文的专业信函 PDF

2️⃣ 用 KaTeX 排版数学公式

在文档目录放一个 config.yml 启用插件即可(参考 test/samples/pug/katex/config.yml):

plugins:
  - katex

生成的 PDF 中公式渲染效果如下:

ReLaXed 使用 KaTeX 插件渲染数学公式的 PDF 页面效果

3️⃣ 为每页添加页眉页脚和页码

用 template#page-footer / template#page-header 定义页脚页眉,#[span.pageNumber] 会自动显示当前页码,效果如下:

ReLaXed 生成的带页眉页脚和页码 Page 1/1 的 PDF 页面

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。

接下来去哪里探索

现在就安装 ReLaXed、写下第一行 Pug,3 分钟后你会得到第一份属于自己的专业 PDF 文档 🎉

登录后查看全文
ReLaXed