TeXstudio

把 TeXstudio 的更新日志一直翻到最后，会看到一些根本不属于 TeXstudio 的条目——那是 Texmaker 的记录。TeXstudio 最初是作为 Texmaker 的扩展集、以「TexMakerX」之名起步的分支，在 2.2 版改名，至今仍带着母项目的历史。这段出身很好地解释了它的性格：自己不带任何可执行文件，写作者需要的东西却全在一个窗口里——编辑器、构建链、PDF 阅读器、拼写与语法检查、文档结构一览。唯独不含 LaTeX 本身。本页讲很多人卡住的构建配置、由 .cwl 支撑的补全、结构视图，以及 SyncTeX。

一个不带 LaTeX 的 LaTeX 集成环境

TeXstudio 是一款以 GPL v2 发布的开源编辑器，可运行于 Windows、macOS、Linux 与 BSD，编译方式是把 pdflatex、latexmk 之类作为外部命令启动。因此安装顺序是固定的：先装 TeX 发行版（TeX Live 或 MiKTeX），再装 TeXstudio。 反过来做，就会陷入「程序能启动、偏偏构建不了」这种难以自查的状态。官方列出的特性包括「超过 1000 个数学符号」的符号面板、交互式拼写检查与语法检查、代码折叠、结构视图，以及「（几乎）达到词级同步」的内置 PDF 阅读器——最后这一条直接通向下文的 SyncTeX。

Build 选项卡与 Commands 选项卡：读懂 txs:///

所有设置都在 Options → Configure TeXstudio 里，与构建有关的是两个选项卡。Commands 选项卡用来写「每条外部命令到底是什么」——可执行文件的路径及其参数；Build 选项卡用来定义把它们组合起来的「元命令」。不勾选左下角的 Show Advanced Options，后者的大部分内容根本看不见。很多人卡住就卡在这里：想改 pdflatex 的参数，却盯着 Build 选项卡看，或者反过来。

日常真正会碰的只有四个操作。Build & View（F5） 先编译再打开 PDF；Compile（F6） 只生成 PDF；View（F7） 打开已有的 PDF；Clean 则清扫 .aux、.toc 之类的中间文件，同时不动最终的 PDF。

元命令的内容不过是一串以 txs:/// 开头的名字，用竖线 | 连接。「Build & View」本质上就是一个两词表达式：「默认编译器，然后默认阅读器」。Commands 选项卡里登记的每一条命令都能用同样的方式引用，因此可以把自制的转换步骤插进链条里。

出厂状态下的默认编译器是 pdfLaTeX，但把它换成 latexmk 是常规做法。latexmk 会检查依赖，为参考文献、索引与交叉引用自动跑够所需的遍数，人就不必去数「要编译几次」。在 Commands 选项卡里这样写。注意 % 展开为 根（主）文档的绝对路径去掉扩展名 ——是根文档，而不是你正在编辑的那个文件。正是这一点决定了多文件项目的行为。

latexmk -pdf -synctex=1 -interaction=nonstopmode -file-line-error %.tex

想按文档切换引擎，第一行的 魔术注释 就够了。TeXstudio 会读 % !TeX program、% !TeX root、% !TeX encoding、% !TeX spellcheck 等等。写上下面这一行，就只有这份文档用 LuaLaTeX 编译，设置对话框一动不动。% !TEX 这一族的确切写法，在 TeXShop 那一页有详细说明。

% !TeX program = lualatex
% !TeX root = ../thesis.tex
% !TeX spellcheck = en_GB

一开始只需固定三项设置

可调项太多，务实的做法是先定下三样：默认编译器、Build & View 的链条、是否启用 SyncTeX。 这三样一旦固定，每次按 F5 都会走同一条路，出问题时排查也就只剩一条线索可拉。

• 以西文为主的文档，就让 latexmk 直接生成 PDF；若是继承来的日文模板，则选 upLaTeX + dvipdfmx。
• 把 Build & View 定义成「我每天按的那个 F5 究竟做什么」，包含编译与用内置阅读器打开这两步。
• 命令里务必写上 -synctex=1 与 -file-line-error：前者用于从 PDF 回到源码，后者让错误带上文件名与行号。
• 打开正式稿之前，先用一个十行的 .tex 试设置，同时看日志和 PDF，确认跑的确实是你预期的引擎。

如何配置日文的构建

广泛使用的路径有两条。一条是 LuaLaTeX：在 Build 选项卡把 Build & View 设为「Compile & View」、默认编译器设为「LuaLaTeX」，按一下 F5 就直达 PDF。若是从零开始，这条更直接。另一条是长期作为日文定式的 upLaTeX + dvipdfmx；由于它在 PDF 之前先经过 DVI，需要把 Build & View 设为「DVI->PDF chain」、默认编译器设为「LaTeX」。

最清爽的安排，是把引擎组合写进 .latexmkrc，而让 TeXstudio 只负责调用 latexmk。把下面这个文件放在 .tex 同一文件夹，upLaTeX → dvipdfmx 的流程、参考文献（upbibtex）、索引（upmendex）以及重跑次数，就都由 latexmk 照料。由于 $latex 里带着 -synctex=1，SyncTeX 也照常可用。

$latex = 'uplatex %O -synctex=1 -interaction=nonstopmode %S';
$bibtex = 'upbibtex %O %B';
$makeindex = 'upmendex %O -o %D %S';
$dvipdf = 'dvipdfmx %O -o %D %S';
$pdf_mode = 3;

$pdf_mode = 3 选定的是「先生成 DVI，再用 $dvipdf 转成 PDF」这一模式。%O（额外选项）、%S（源文件）、%B（不含扩展名的基名）、%D（输出目标）是 latexmk 的占位符，和 TeXstudio 的 % 不是一回事。这样安排之后，无论从 TeXstudio 调用、从命令行敲、还是从别的编辑器启动，结果都一致——因为配置只有一处。

日志要从第一个错误读起

在盲目改设置之前，先看两件事：启动的是哪条命令，以及日志里的第一个错误是什么。LaTeX 的错误会连锁，第一条红色行往往制造了后面所有的红色行。TeXstudio 的日志面板正是按这个阅读顺序设计的：可以在原始日志与分类表格之间切换，表格把消息分为错误（红）、警告（黄）与过满盒子（蓝）。在错误之间移动用 Ctrl+Shift+↑／Ctrl+Shift+↓，在警告与盒子之间移动用 Alt+Shift+↑／Alt+Shift+↓。

• 看到 Could not start the command，该怀疑的是 PATH 与 TeX Live／MiKTeX 的安装状态，而不是 TeXstudio。请检查 Commands 选项卡里的可执行文件路径。
• File not found 无非三种情况：根文件、相对路径、图片文件名——顺便看看扩展名是否写全。
• 缺宏包时，TeX Live 用 tlmgr install，MiKTeX 用 MiKTeX Console 安装。这件事编辑器解决不了。
• 点击日志里的行号，只修第一个错误，重新构建后再往下读。先读连锁末端往往是白费工夫。

补全为何知道你的 \label：.cwl 文件

TeXstudio 并不在解析 LaTeX，它读的是 .cwl 文件——completion word list（补全词表）。这个格式最初来自另一款 LaTeX 编辑器 Kile，TeXstudio 在其上添加了语义信息：这个参数是标签，那个位置该落光标。所以打到 \ref{ 会列出文档里的标签，打到 \cite{ 会列出文献的键（bibID）。当你 \usepackage 某个宏包时，若存在对应的 cwl 就加载它；若不存在，TeXstudio 会从 .sty 自动生成——那样只能得到命令名，得不到参数的含义。自制宏包写成 \usepackage{./myPackage} 这样的相对路径，TeXstudio 就会去找 ./myPackage.cwl。

还有三个省按键的机关值得记住。当候选项共享同一前缀时，按 Tab 会一次补齐这段公共部分。开始写一个环境——比如打出 \begin{itemize}——对应的 \end{itemize} 会自动补上。把光标在环境名上停一会儿，会出现 镜像光标，可以同时改写 \begin 与 \end 里的名字——把 itemize 改成 enumerate 一步到位。想闭合当前尚未闭合的环境或括号，按 Alt+Return。忘记闭合是 LaTeX 最常见的事故之一，这一手值得记牢。

结构视图，以及边打字边跑的拼写与语法检查

左侧的 结构视图（Structure view） 就是文档的地图。上面列出标题（\section 一族）、标签（\label）、由 \input／\include 引入的文件、beamer 的 block，以及 TODO——\todo{} 命令和 % TODO／%todo 注释都会被收进来。点击条目即可跳到相应位置。无论稿子多长、文件多少，正是这份清单让你不至于迷失当前位置。

拼写检查在你敲字的同时运行，对可疑词右键即可看到候选更正。词典采用 hunspell 格式——与 LibreOffice、Firefox 同一套机制，因此额外的词典可以直接借用。想把语言固定到某个文件，就在第一行写 % !TeX spellcheck = de_DE，每次打开该文件都会自动切到那个语言。编多语种论文集时尤其管用。

语法检查则并非 TeXstudio 自己在判断。开源校对引擎 LanguageTool 以服务器形式在本地运行，TeXstudio 启动时连上它，把写完的段落发过去再取回结果（在 Options → Configure TeXstudio → Language Checking 里指定服务器 URL 与 jar 路径）。正因为是这种结构，你的文字不会离开本机——处理尚未投出的稿件时，这一点让人安心。

SyncTeX：Ctrl+点击，正向反向皆可

条件只有两个。其一，给编译命令传 -synctex=1。 SyncTeX 不是编辑器的功能，而是 TeX 引擎的功能，这个开关才会让它写出同步文件 .synctex.gz（上文的 latexmk 行与 .latexmkrc 里都已带上；若忘了，TeXstudio 会主动提出替你修正命令）。其二，用内置阅读器打开 PDF。 让双向跳转成为可能的，正是这个内置阅读器对 SyncTeX 的支持。

操作很好记，两个方向都是 Ctrl + 左键点击。在源码里这样点，就跳到 PDF 中对应的位置（正向搜索）；在 PDF 里这样点，就跳回对应的源码行（反向搜索）。右键菜单里的「Go To PDF」与「jump to source」也能做同样的事。此外，每次打开阅读器时，都会自动朝当前光标位置执行一次正向搜索。再启用「scrolling follows cursor」与「cursor follows scrolling」，两边就在写作全程保持联动，校对时「这一段是哪一行写出来的」这种寻找也就不存在了。