SwiftLaTeX/SwiftLaTeX · 上手攻略

仓库：SwiftLaTeX/SwiftLaTeX
链接：https://github.com/SwiftLaX/SwiftLaTeX
分类：academic-writing
作者：Tom
更新：2026-08-20

这是什么

SwiftLaTeX 是一个基于 WebAssembly 的浏览器端 LaTeX 编辑器/引擎，支持 PdfTeX 和 XeTeX 两种引擎，在浏览器中完全本地运行（所有计算不经过服务器），可选 WYSIWYG（所见即所得）编辑模式。

官方 Demo：https://www.swiftlatex.com

解决什么问题

传统的 LaTeX 编写需要本地安装完整的 TeX 发行版（如 TeX Live 或 MiKTeX），安装包体积庞大（数 GB），配置繁琐。SwiftLaTeX 将 TeX 引擎编译为 WebAssembly，让任何有浏览器的设备都能直接编译 LaTeX 文档，无需安装任何本地软件。对于嵌入 LaTeX 到网页、在线文档平台或教育场景，SwiftLaTeX 提供了一种轻量级解决方案。

快速安装

方式一：在线使用（推荐尝鲜）

直接访问 https://www.swiftlatex.com 使用在线编辑器，无需任何安装。

方式二：自托管（网页嵌入）

从 GitHub Releases 下载最新打包文件，放入网页目录：

<script src="PdfTeXEngine.js"></script>

然后初始化引擎（见核心用法）。

方式三：从源码编译

需要 Emscripten SDK（emsdk）：

# 克隆 emsdk
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk

# 安装最新 SDK
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh

# 编译 XeTeX 或 PdfTeX WASM 模块
cd pdftex.wasm   # 或 xetex.wasm
make

⚠️ 源码编译依赖 Emscripten，整个过程需要较长时间（约数十分钟），非开发者通常不需要这一步。

核心用法

方式一：网页嵌入（最典型用法）

<!DOCTYPE html>
<html>
<head>
  <title>SwiftLaTeX Demo</title>
  <script src="PdfTeXEngine.js"></script>
</head>
<body>
  <button onclick="compile()">Compile</button>
  <pre id="log"></pre>
  <script>
    async function compile() {
      const engine = new PdfTeXEngine();
      const logEl = document.getElementById('log');

      await engine.loadEngine();
      logEl.textContent = 'Engine loaded.';

      engine.writeMemFSFile("main.tex",
        "\\documentclass{article}\n" +
        "\\begin{document}\n" +
        "Hello, SwiftLaTeX!\n" +
        "\\end{document}"
      );

      engine.setEngineMainFile("main.tex");
      let result = await engine.compileLaTeX();

      logEl.textContent = result.log;  // 输出编译日志
      // result.pdf 包含 PDF 二进制数据
      console.log("PDF size:", result.pdf.length, "bytes");
    }
  </script>
</body>
</html>

方式二：在线编辑器

打开 https://www.swiftlatex.com
在左侧编辑器输入 LaTeX 代码
点击编译，右侧预览 PDF
支持 XeTeX 和 PdfTeX 引擎切换

核心 API 速查

API	返回值	说明
`engine.loadEngine()`	`Promise`	异步加载 WebAssembly 引擎（首次调用约需数秒）
`engine.isReady()`	`boolean`	检查引擎是否就绪
`engine.writeMemFSFile(filename, content)`	`void`	上传 .tex 源文件或资源（支持 string 或 Uint8Array）
`engine.makeMemFSFolder(folder)`	`void`	创建目录
`engine.setEngineMainFile(filename)`	`void`	指定入口 .tex 文件
`engine.compileLaTeX()`	`Promise<CompileResult>`	执行编译，返回 `{ log, pdf }`
`engine.flushCache()`	`void`	清空所有已上传文件
`engine.closeWorker()`	`void`	关闭 Web Worker，释放资源

引擎选择建议

引擎	适用场景	字体支持	速度
XeTeX（推荐）	通用场景、中文、Unicode 内容	OpenType / TrueType，开箱即用	略慢
PdfTeX	纯英文、快速编译	TeX 内置字体	较快

⚠️ XeTeX 引擎不包含完整 ICU 数据集，locale 相关的断行行为可能与原生 XeTeX 有差异。如仅处理英文文档，PdfTeX 更快更稳定。

首次编译网络依赖

首次编译时，引擎需要从 CTAN 或 SwiftLaTeX 镜像服务器（https://texlive.swiftlatex.com）下载所需的宏包文件。有网速较慢或内网环境的用户，可自建 TeX Live 镜像服务器（参见 SwiftLaTeX/Texlive-Ondemand 仓库），并通过 engine.setTexliveEndpoint(url) 指定。

典型适用场景

在线 LaTeX 编辑器：嵌入博客或在线教育平台，让用户无需本地安装 TeX 即可编写 LaTeX
网页端论文预览：作者可在任何设备浏览器中实时预览论文排版效果
自动化文档生成：服务端或客户端根据模板生成 PDF，无需安装完整 TeX 发行版
轻量级 LaTeX 教学：学生直接在浏览器实验，无需配置本地环境
嵌入式 LaTeX 渲染：在不支持本地 TeX 的嵌入式设备或受限环境中使用

坑与注意

性能约为原生 2 倍慢：官方称运行速度约为原生二倍，复杂文档（多图表、多次编译引用）的等待时间会明显更长。
首次编译需下载宏包：TeX Live 宏包按需下载，首次编译时如果网络不佳可能失败。可预先缓存或自建镜像服务器。
中文支持依赖 XeTeX 引擎：PdfTeX 不直接支持中文，需要用 XeTeX + fontspec 宏包，或自行配置 ctex 等中文宏包支持。
WYSIWYG 模式仍在开发中（README 原话 WIP）：目前主要使用代码编辑 + PDF 预览模式，不要期待完整的所见即所得体验。
GitHub 仓库 2022 年后更新较少：SwiftLaTeX 核心引擎已稳定，但社区活跃度和新功能推进较慢。使用前评估是否满足你的功能需求。
AGPL-3.0 许可证：如在商业产品中使用，注意 AGPL 的传染性——修改的源代码需开源。
Emscripten 编译环境复杂：一般用户无需从源码编译，但如果需要自定义引擎或修改 WASM 模块，需要配置 Emscripten 环境。

与同类对比

工具	实现方式	是否开源	中文支持	性能	适合场景
SwiftLaTeX	WebAssembly（纯浏览器）	AGPL-3.0	XeTeX 支持	约原生 2x 慢	嵌入网页、轻量编辑
Overleaf	服务器端编译	闭源（社区版开源）	完整	原生速度	多人协作、完整功能
Papeeria	云端编译	闭源	完整	原生速度	在线协作写作
Authorea	云端编译	闭源	完整	原生速度	学术出版平台
CoCalc	云端 Jupyter + LaTeX	部分开源	完整	原生速度	教学、计算环境

SwiftLaTeX 的最大优势是完全客户端运行、不需要服务器——数据不会离开用户的浏览器，适合隐私敏感场景或作为嵌入式组件。劣势是功能完整度不如 Overleaf 等成熟平台。

一句话推荐结论

如果你需要在一个网页或博客中嵌入 LaTeX 编译能力，或者给无法安装 TeX 环境的用户提供在线 LaTeX 编辑体验，SwiftLaTeX 是目前最轻量、最直接的开源解决方案；作为日常主力 LaTeX 编辑器，Overleaf 等成熟平台仍是更稳妥的选择。