企业官网建设流程全解析

Zettlr 的 LaTeX 安装指南：为 Markdown 导出 PDF 铺平道路

【免费下载链接】ZettlrYour One-Stop Publication Workbench项目地址: https://gitcode.com/GitHub_Trending/ze/Zettlr

导读

本文围绕 Zettlr 内置的《LaTeX Guide》教程展开，讲清一个核心问题：为什么 Zettlr 建议你尽快安装 LaTeX，以及 Windows、macOS、Linux 三大平台各自推荐哪套 LaTeX 发行版。读完本文，你将了解 LaTeX 在 Zettlr 导出链路（Markdown → PDF）中的具体位置，掌握各平台的最小化安装方案，并能根据仓库内的默认导出配置（如 XeLaTeX PDF.yaml）自行判断需要补齐哪些 TeX 包。

LaTeX 对 Zettlr 意味着什么

Zettlr 是一款以 Markdown 为核心的写作工具，但现实世界中的协作对象往往是 Word 文档或 PDF。Zettlr 的官方教程明确建议：尽早安装 LaTeX，以便导出你的所有文件，并更好地与同事协作（原文见 static/tutorial/pt/LaTeX Guide.md 与对应的英文版 static/tutorial/en/LaTeX Guide.md）。原因很直白：

• LaTeX 免费开源，且在所有主流操作系统上均可运行；
• 即使你全面转向 Markdown，仍然需要处理 Word 文档，并把成果分享给不使用 Markdown 的协作者；
• Zettlr 的 PDF 导出引擎之一——XeLaTeX——依赖完整的 TeX 套件，没有 LaTeX 就无法走这条导出路径。

需要说明的是：LaTeX 并不是 Zettlr 的"可选插件"，而是其导出能力的地基之一。Zettlr 内置了 Pandoc 负责文档转换（scripts/get-pandoc.sh 会为各平台下载捆绑的 Pandoc 二进制，environment-check.ts 在启动时检测并设置PANDOC_PATH），而 Pandoc 生成 PDF 时又需要调用 TeX 引擎，这就是 LaTeX 必须单独安装的根本原因。

三大平台的 LaTeX 发行版推荐

官方教程给出的推荐非常明确，按平台划分如下（安装时请认准发行版名称，避免装错）：

三个关键细节值得展开：

1. macOS 装 Basic TeX 就够了：MacTeX 完整版体积很大，官方教程特意强调 Basic TeX 版本即可满足 Zettlr 的导出需求，安装后无需额外配置。
2. Linux 的texlive-xetex很关键：Zettlr 的 PDF 导出默认使用 XeLaTeX 引擎（见下文配置分析），而该引擎由texlive-xetex包提供。只装texlive-base可能导致 XeLaTeX 缺失，导出时报错，因此教程专门提醒你可能需要追加安装。
3. 安装方式统一：三个平台都可以用各自的"标准安装器"完成安装，无需手工编译源码。

为什么默认引擎是 XeLaTeX：解析默认导出配置

Zettlr 的导出不是临时拼命令，而是基于仓库内置的 Pandoc defaults 文件。PDF 导出的默认配置位于 static/defaults/XeLaTeX PDF.yaml，其中与 LaTeX 直接相关的核心参数如下：

# Conversion: Markdown --> PDF (requires TeX suite to be installed) reader: markdown writer: pdf self-contained: true variables: # Sets the size of the document's pages. papersize: a4 # Possible values: a0-a6, b0-b6, c0-c6, b0j, letter, executive, legal filters: - type: citeproc pdf-engine: xelatex # Change this if you want to use a different engine, e.g. pdflatex toc: false # Include a table of contents? toc-depth: 2 # 2 means to only include headings level 1 and 2 in the ToC number-sections: false highlight-style: pygments

参数解读：

• pdf-engine: xelatex：指定 PDF 生成引擎为 XeLaTeX。注释明确写道"Change this if you want to use a different engine, e.g. pdflatex"，也就是说你可以按需改成pdflatex、lualatex等，但前提是你的 TeX 发行版里装了对应引擎——这正是 Linux 上需要texlive-xetex的原因。
• papersize: a4：默认 A4 纸张，可取值包括a0–a6、b0–b6、c0–c6、b0j、letter、executive、legal，按出版物要求调整即可。
• toc/toc-depth/number-sections：控制目录生成与章节编号，默认关闭目录、不编号章节，适合普通写作；需要正式排版时再打开。
• filters: [citeproc]：启用引文处理，配合 Zettlr 的引文库与 CSL 样式在导出时渲染参考文献。
• self-contained: true：产出自包含的 PDF，图片等资源会被内嵌。

此外，仓库还提供了 static/defaults/LaTeX.yaml，用于把 Markdown 直接导出为.tex源码（writer: latex），并设置了top-level-division: chapter、wrap: none、columns: 78等面向 LaTeX 源码阅读的参数。这说明 Zettlr 的 LaTeX 能力分两条线：一条是直接生成 LaTeX 源码，另一条是经 XeLaTeX 引擎产出最终 PDF。

Zettlr 的两条 PDF 导出路径：源码视角

从导出插件的实现可以更清楚地看到 LaTeX 的位置。在 pdf-exporter.ts 的文件头注释中写明，PDF 导出插件提供两种变体：

"chromium-pdf" exports by exporting to HTML and then utilising the Chrome print API to generate a PDF. The xelatex exporter is more powerful, but requires a full TeX installation on the system.

翻译过来就是：

• Simple PDF（Chromium 打印路径）：先把 Markdown 转成 HTML，再调用 Chromium 的打印 API（webContents.printToPDF）生成 PDF。这条路径不需要 LaTeX，但功能相对基础（如代码所示，仅支持 A4、纵向、无背景打印等固定参数）。
• XeLaTeX 路径：通过 Pandoc 调用 XeLaTeX 排版生成 PDF，功能更强（目录、页码、字号、参考文献排版等），但要求系统装有完整的 TeX 套件。

两条路径的分发逻辑在 exporter/index.ts 的makeExport中：当 profile 的 writer 为simple-pdf时走 Chromium 插件，否则走 Pandoc 默认导出插件。换言之：不装 LaTeX，你仍能用"Simple PDF"导出；但想用 XeLaTeX 的高质量排版，就必须先装好 TeX 发行版。

Zettlr 调用 Pandoc 的方式也值得留意：spawn('pandoc', ['--defaults', defaultsFile])，即先生成一份临时的 defaults YAML（合并用户设置、CSL 样式、Lua 过滤器等），再交给 Pandoc 执行（见 exporter/index.ts 的runPandoc与writeDefaults）。因此你的 LaTeX 安装只需要保证xelatex可被 Pandoc 调用即可，无需在 Zettlr 里做任何额外配置。

安装后的验证与常见问题

安装完成后如何确认 Zettlr 能用上 LaTeX？

1. 命令行验证：在终端运行xelatex --version，能输出版本信息即表示 XeLaTeX 可用；Linux 用户若提示命令不存在，说明texlive-xetex尚未安装。
2. 在 Zettlr 中试导出：打开任意 Markdown 文档，选择 PDF（XeLaTeX）导出格式。若导出成功且包含正常排版（字体、页码、目录等），说明 LaTeX 链路畅通；若弹出引擎缺失或编译错误，优先检查 TeX 发行版是否完整。
3. 注意 PATH 环境：在 macOS 与 Linux 上，GUI 应用不一定继承终端里的PATH。Zettlr 的启动环境检查会调用fixPath()修复此问题，以便正确探测 Pandoc 等辅助程序（见 environment-check.ts）。若系统检测异常，可在终端手动确认xelatex的安装路径是否在 PATH 中。

如果只想快速出 PDF 而不想安装庞大 TeX 套件，可以暂时使用 Zettlr 内置的"Simple PDF"（Chromium 打印）导出；但官方推荐仍是在尽早的阶段安装 LaTeX——它不仅是导出 PDF 的刚需，也为后续处理 Word 文档、与不熟悉 Markdown 的同事协作扫清障碍。

小结

• LaTeX 是 Zettlr 高质量 PDF 导出的地基，官方推荐尽早安装；
• Windows 用 MiKTeX，macOS 装 MacTeX 的 Basic TeX 即可，Linux 用 TeX Live 并确保安装texlive-base与texlive-xetex；
• Zettlr 默认以xelatex作为 PDF 引擎，可通过 XeLaTeX PDF.yaml 调整引擎与排版参数；
• 不装 LaTeX 仍可走"Simple PDF"（Chromium 打印）导出，但排版能力受限；
• Pandoc 由 Zettlr 捆绑提供，你只需保证 TeX 引擎可被系统调用。

对照官方教程原文（static/tutorial/pt/LaTeX Guide.md），本文已完整覆盖其全部要点，并补充了默认导出配置、导出插件实现与启动环境检查等仓库源码层面的细节，帮助你既装得对，也理解为什么这样装。

【免费下载链接】ZettlrYour One-Stop Publication Workbench项目地址: https://gitcode.com/GitHub_Trending/ze/Zettlr