Neovim + tree-sitter 打造 LaTeX 精准语法高亮与结构化编辑

1. 为什么我坚持让Neovim用tree-sitter解析LaTeX

说实话，用Neovim写LaTeX这件事，我前两年一直是带着妥协心态在做。语法高亮能用，但总差点意思：\begin{equation}里面的内容经常被当成普通文本，\frac{分子}{分母}的分子分母颜色分不出来，命令参数和正文混在一起，整篇文档看起来就是一片混沌。直到我把tree-sitter接进来，这个体验才算真正脱胎换骨。这篇文章不聊怎么装Neovim，也不重复LaTeX入门，只聚焦一件事：让树形解析器（tree-sitter）为LaTeX文档提供精确的语法分析和高亮，同时把配套的文本对象、折叠、补全一起理顺。

这套方案适合谁？如果你已经在用Neovim写LaTeX，但高亮还是靠传统正则语法文件撑着；或者你刚听说tree-sitter想试一试但不知从何下手；再或者你已经装了tree-sitter，却发现对LaTeX的支持没有想象中好用——那这篇文章就是写给你的。我会把原理、配置、踩坑、调优一次讲完。

1.1 传统正则高亮的困境

要理解tree-sitter的价值，先得知道传统Vim/Neovim语法高亮是怎么工作的。老方案本质上是正则表达式匹配：syntax文件里定义了一堆规则，比如“以\开头直到空格或{ 的字符串算命令”，“\begin{...}和\end{...}之间的内容算环境”。这些规则按优先级叠在一起，逐行扫描文本。

这套机制对付简单语言没问题，但LaTeX的语法结构其实是高度嵌套的。一个导言区里的\newcommand可以定义新命令，定义里可能又有分组、又有可选参数；一个数学环境里可能有半个页面的公式嵌套；$...$、\[...\]、\begin{align}这些数学环境的边界如果靠正则去判断，稍微复杂一点就误判。典型的情况就是：编辑器把\frac后面的第一对花括号当普通文本，里面再嵌套一个\sqrt的时候，整段高亮就崩了。

还有一个更隐蔽的问题：正则高亮是“状态机”式的，它在扫描文本时维护一个状态标志，比如“当前是否在数学环境内”。一旦文档里出现未闭合的环境、注释里写了个$符号、或者\usepackage的参数里碰巧有特殊字符，状态就会错乱，剩下的整个文档全部高亮错误。这种问题在写长论文的时候特别常见，排查起来又很难受——你盯着屏幕，明知道高亮不对，却说不清是文档写错了还是编辑器疯了。

1.2 tree-sitter的语法树机制和LaTeX的适配

tree-sitter的做法完全不一样。它在打开文件时会把整个文档解析成一棵具体的语法树（CST，具体语法树），每个节点都对应文档里的一段文本，并且带着明确的类型信息。比如\frac{a}{b}会被解析成一个function_call或generic_command节点，其中a和b是清晰的参数节点，跟周围文本的从属关系一目了然。高亮不再是“猜”，而是直接查这棵树的节点类型和捕获名（capture name）。

这种机制对LaTeX这种结构化语言来说几乎是量身定做的。LaTeX的文档结构本身就是一个树：document环境是根，下面是段落、列表、公式、表格，公式里又嵌套分数、根号、上下标。tree-sitter解析器能忠实还原这个结构，所以高亮可以做到非常细粒度：命令名一个颜色，必选参数一个颜色，可选参数一个颜色，注释、数学符号、标点都有各自的归属。

tree-sitter还有一个关键特性是增量解析（incremental parsing）。它只重新解析文档中被修改的区域以及受影响的少量上下文，而不是每次按键都把整个文件重新扫一遍。这意味着哪怕你打开一个几百KB的LaTeX文档，连续输入的时候也不会感到卡顿。这一点在后文的性能部分我会展开讲，先记住这个结论：tree-sitter的解析速度和准确性，都不是传统正则方案能比的。

1.3 维护成本和扩展性

选择tree-sitter另一个隐形好处是生态。tree-sitter本身是一个通用的增量解析框架，社区为它维护了大量语言的grammar。对LaTeX来说，有一个专门的tree-sitter-latex解析器项目，持续在更新。这意味着你不只是获得“今天能用的高亮”，而是获得了一个持续演进的语法分析基础设施。

更实际的好处是，基于语法树可以做很多传统方案做不了的事：按环境选中、跳到下一个环境、精确折叠、给定制的代码操作提供语义信息。这些能力我在第三节和第五节会详细演示。如果你以后还想让Neovim理解LaTeX的宏定义、实现语义级别的跳转，tree-sitter铺好的这条数据通路就是基础。

2. 配置前的准备与安装

开始配置之前，先把环境要求说清楚，避免后面卡壳。

2.1 环境要求

首先是Neovim的版本。tree-sitter的客户端支持从Neovim 0.5开始就有了，但真正好用、API稳定是在0.9以后。我建议直接用0.9或0.10以上的版本，最好是当前最新的稳定版。0.7、0.8这些老版本虽然也能跑，但某些捕获名和查询语法不兼容，你会遇到“配置照抄了却无效”的问题。

其次是编译器。tree-sitter的parser在安装时有两种方式：一是用预编译的二进制，二是从源码用C编译器编译。很多Linux发行版和macOS的包管理器能提供预编译parser，但如果你走源码编译路线（这也是最常见的兜底方案），就需要系统里有cc或gcc。Windows用户尤其要注意：如果你不是用WSL，而是直接在Windows上跑Neovim，需要先装一个能用的C编译器，比如MSVC或MinGW。我见过很多人在这一步卡住——parser一直编译失败，最后发现是编译器没装好。

顺带提一句热词里很多人搜过的“latex路径没加到系统路径”。这事跟Neovim配置无关，但如果你在Neovim里调latexmk或latex命令时一直提示找不到，八成是系统PATH里没有TeX发行版的bin目录。Windows上装完TeX Live或MiKTeX后，有个选项是“Add to system PATH”，装的时候没勾，后面就得去环境变量里手动加。Linux/macOS一般在/usr/local/texlive/<版本>/bin/<平台>，要确保shell能找到。

2.2 安装tree-sitter-latex parser

我用的插件管理器是lazy.nvim，现在Neovim社区用这个的也最多。核心插件是nvim-treesitter，它负责parser的下载、编译和加载，以及提供默认的高亮、缩进、折叠模块。

安装配置如下：

lua复制{
  "nvim-treesitter/nvim-treesitter",
  build = ":TSUpdate",
  config = function()
    require("nvim-treesitter.configs").setup({
      ensure_installed = { "latex" },
      highlight = { enable = true },
      indent = { enable = true },
    })
  end,
}

没错，LaTeX的parser语言名就叫latex。ensure_installed会保证这个parser被装好；build = ":TSUpdate"是让插件在更新时同步更新所有parser。这个配置装好后，第一次打开.tex文件时，或者手动执行:TSInstall latex，Neovim就会把tree-sitter-latex拉下来编译。

装完以后可以用:TSInstallInfo检查parser状态，看到latex: ✓ installed就说明成功了。如果用:TSInstall latex遇到网络问题，可以考虑配置镜像源，但最常见的问题还是缺编译器，这一步先排查清楚。

2.3 启用高亮和增量解析

highlight = { enable = true }这行配置启用了tree-sitter高亮。实际上从Neovim 0.9开始，你可以不用nvim-treesitter的highlight模块，直接在自己的配置里对每种文件类型调用vim.treesitter.start()。但用nvim-treesitter的好处是它帮你处理了很多默认capture和fallback逻辑，对大多数用户来说更省事。

有一点需要强调：nvim-treesitter的highlight模块启用后，会接管当前buffer的语法高亮。如果你以前装过别的语法插件，比如vim-polyglot或者传统的.vim高亮文件，需要留意冲突。建议在启用了tree-sitter的文件类型上关闭传统语法文件的干扰，或者在插件优先级上做调整。最常见的现象是“两种高亮打架，颜色一会儿对一会儿不对”，通常就是多个高亮源同时存在导致的。

至于增量解析，tree-sitter本身就在后台工作，不需要额外配置。你只需要在写大文档时体会一下“输入流畅不卡顿”的感觉就行了。真正的性能调优我在第四节单独讲。

3. 自定义高亮与配套功能

装好parser只是第一步，真正让体验起飞的是理解高亮capture，然后按自己的喜好定制。section这部分我会先解剖默认高亮分组，再演示怎么用query写自定义规则，最后介绍一个很多人不知道的福利：基于语法树的文本对象。

3.1 默认高亮分组解析

nvim-treesitter为所有语言定义了一套统一的capture体系，LaTeX的parser会把这些capture映射到具体的语法节点上。比如：

• @keyword：\begin、\end这类环境控制词
• @function：自定义命令名，如\frac、\text、\cite
• @parameter：命令的必选参数（花括号里的内容）
• @string：可选参数或普通文本参数里的字符串
• @comment：%开头的注释
• @operator：数学环境里的运算符符号
• @punctuation.bracket：花括号本身

这些capture会映射到你的colorscheme里的高亮组。比如@function通常映射到Function高亮组，@string映射到String。所以默认情况下，你不需要额外配置就能获得一套合理的高亮——命令名、参数、注释各有各的颜色。

但我个人的经验是，默认分组对LaTeX来说还不够细致。比如在\begin{equation}里，\begin和equation两个部分其实是不同的语义：\begin是环境控制词，equation是环境名。很多默认主题会把它们当成同一个@keyword处理，显示成同一种颜色。我习惯把环境名跟环境控制词区分开，这样扫一眼就知道当前在什么环境里。这个就需要写自定义query了。

3.2 用query自定义高亮

tree-sitter的自定义高亮通过query文件来实现。在nvim-treesitter的配置里，你可以在nvim的runtimepath下放queries/latex/highlights.scm文件，它会覆盖或追加默认的capture规则。

举个例子，我想把环境名单独提取出来，突出显示环境边界。先要看看parser实际把节点命名成什么。用:InspectTree命令，把光标放在\begin{equation}那行，会看到类似这样的节点结构：

code复制(generic_environment
  begin: (environment_name) @_name
  ...
)

了解节点名之后，可以在highlights.scm里加规则：

scheme复制(environment_name) @namespace

这样环境名就会走@namespace高亮组，在大多数colorscheme里是区别于普通关键词的另一种颜色。再比如，我想让\label{...}的参数显示成特殊颜色，方便快速找到引用标签：

scheme复制(generic_command
  name: (command_name) @function
  (group
    (curly_group
      text: (text) @label.reference)))

这种写法看起来复杂，但其实逻辑很直白：match到generic_command节点，它的名字部分是普通命令，它第一个curly_group里的文本作为标签引用。写query的诀窍是先:InspectTree看节点结构，再照着结构写匹配规则。这个过程不要求你成为tree-sitter专家，多试几次就能掌握。

还有一个小技巧：如果只想在某个colorscheme下微调颜色，可以定义一个自定义高亮组，然后在colorscheme加载后通过vim.api.nvim_set_hl()设置颜色。比如：

lua复制vim.api.nvim_set_hl(0, "@label.reference", { fg = "#ffd700" })

这里@label.reference是自定义capture名，可以在query里直接使用。这种方式比直接改colorscheme文件灵活得多，换主题也不用改。

3.3 基于语法树的文本对象操作

这是我认为tree-sitter给Neovim带来最实用、却又最容易被忽略的能力之一。传统Vim有ci"、da(这些基于字符的文本对象，但从来没有“环境”这个层面的文本对象。tree-sitter配合nvim-treesitter-textobjects插件，让你可以用cie一次选中整个\begin{equation}...\end{equation}环境里的内容。

我用的配置示例：

lua复制{
  "nvim-treesitter/nvim-treesitter-textobjects",
  dependencies = { "nvim-treesitter/nvim-treesitter" },
  config = function()
    require("nvim-treesitter-textobjects").setup({
      select = {
        enable = true,
        lookahead = true,
        keymaps = {
          ["ae"] = "@environment.outer",
          ["ie"] = "@environment.inner",
          ["ac"] = "@command.outer",
          ["ic"] = "@command.inner",
        },
      },
    })
  end,
}

@environment.outer和@environment.inner对应LaTeX环境节点的外层（包括\begin和\end）和内层（只包括环境内容）。这样当你把光标放在一个itemize环境中间，按vae就能选中整个环境，按die能把环境内容删除但不破坏\begin和\end。对经常要调整表格、公式结构的人来说，这个效率提升是肉眼可见的。

我实际用下来最舒服的操作是配合c命令：cie选中环境内容，然后直接输入新的内容，相当于一键重写一个环境。传统Vim里要手动选几行、或者写宏，现在一行指令搞定。这就是语法树带来的“结构性操作”能力。

4. 常见问题排查与性能调优

配置过程中一定会遇到各种问题。我把踩过的坑和解决方案整理成下面的速查表，按问题的出现频率排序。

4.1 parser安装失败怎么办

我特别想说一下Windows的问题。不是每个人都有WSL开发环境，但Windows原生跑Neovim + tree-sitter确实坑多。parser编译需要C编译器，很多人的Windows上并没有。我建议要么用WSL彻底改善体验，要么在Windows上装一个MinGW-w64，然后把gcc加到PATH里。装好之后再:TSInstall latex，基本就顺畅了。

4.2 高亮不生效的原因

高亮不生效是最常见的问题，而且90%的情况不是parser没装好，而是配置逻辑不对。

如果你用了nvim-treesitter的highlight模块，注意ensure_installed和highlight.enable是两个层面的事：前者管安装parser，后者管启用高亮。很多人只写了ensure_installed忘了highlight = { enable = true }，parser装了但高亮还是老样子。

还有一种情况是：filetype不对。如果你用了一些插件把.tex文件识别成了其他文件类型（比如某些插件会认成plaintex），tree-sitter的parser就匹配不上，高亮自然不生效。解决方法是确保文件类型是tex，或者在配置里显式映射：

lua复制vim.filetype.add({ extension = { tex = "tex" } })

4.3 与vimtex、fold的冲突处理

很多写LaTeX的Neovim用户同时装了vimtex。vimtex有自己的折叠方式（基于\section等结构）和语法高亮补充（比如\cite的引用高亮）。当tree-sitter也启用高亮时，可能会有视觉冲突或性能问题。

我推荐的组合是：让vimtex负责编译、正向搜索、片段和部分个性化功能，关闭vimtex对语法高亮和折叠的接管，把这两块交给tree-sitter。vimtex的高亮相关设置：

lua复制vim.g.vimtex_syntax_enabled = 0 -- 关闭vimtex自带的语法高亮
vim.g.vimtex_fold_enabled = 0   -- 关闭vimtex的折叠，改用tree-sitter折叠

折叠这块另一个容易踩的坑是：如果开了tree-sitter的indent模块，再结合foldmethod=expr和foldexpr=nvim_treesitter#foldexpr()，在长文档里可能出现折叠计算卡顿。我建议折叠还是用传统方法，或者干脆推迟到写完整章再折叠，写的时候不折叠。具体性能问题见下一节。

4.4 长文档的性能调优

LaTeX长文档动辄几百KB，tree-sitter的增量解析虽然快，但高亮渲染和query匹配在节点特别多的时候还是会感到迟滞。我在写一本书（大约1200页英文文档）时遇到过输入延迟，后来做了三件事：

一是把tree-sitter的highlight模块里additional_vim_regex_highlighting关掉。这个选项默认是开启的，启用了传统正则高亮作为补充，但代价是两套高亮同时跑，性能直接翻倍下降。在高版本Neovim中，如果已经全面用tree-sitter高亮，完全没有必要开正则补充：

lua复制highlight = {
  enable = true,
  additional_vim_regex_highlighting = false,
},

二是fold尽量少开。tree-sitter的折叠计算不便宜，如果文档节点树非常深（LaTeX的嵌套本来就深），建议只在需要看结构的时候临时打开折叠，平时保持foldmethod=manual或indent，别用expr。

三是如果文档真的超大，考虑按章节拆分文件，用\input或\include组合。这不只是为了Neovim性能，也对编译速度有好处。实际上很多大型项目天生就是分文件的，Neovim的tree-sitter在单文件上的压力自然就小了。

5. 与vimtex、texlab的分工协作

如果你追求的是一个能“日常写论文不打开IDE”的LaTeX环境，那么光有tree-sitter还不够。tree-sitter解决的是语法分析和编辑体验的底层，但编译、补全、文档预览这些还需要别的工具。最好的工作方式不是让一个插件干所有事，而是让它们各司其职。

5.1 三件套的分工

tree-sitter负责三件事：精确高亮、结构化文本对象（cie、vae这类操作）、在nvim-treesitter体系内的缩进和折叠基础。它不负责编译LaTeX，也不负责提供\begin{}的自动补全（虽然可以用片段实现）。

vimtex负责LaTeX编译、正向搜索（从Neovim跳到PDF的对应位置）、反向搜索、\cite和\ref的补全、以及一些LaTeX专属的文本对象（比如csc选中当前章节）。vimtex跟tree-sitter是互补关系，不冲突——前提是别让两者抢高亮和折叠的活，配置见4.3。

texlab是Language Server Protocol（LSP）实现，负责更智能的语言服务：诊断错误（缺引用的包、未闭合环境）、悬停查看命令定义、完整的补全（包括命令、引用、标签、bib条目）、以及重命名符号。这个补全能力是vimtex和tree-sitter给不了的。

用生活类比的话：tree-sitter是眼睛和手，负责看清楚结构和精准编辑；vimtex是手脚和跑腿，负责把文档编译出来并在PDF里找到位置；texlab是大脑，负责理解语义和提示下一步操作。三者配合，才是一套完整的写作工作流。

5.2 推荐配置示例

下面是一份我目前在用的简约配置骨架。nvim-treesitter和nvim-treesitter-textobjects的配置前文已经给出，这里补充vimtex和lspconfig（texlab）的部分。

vimtex的核心配置：

lua复制{
  "lervag/vimtex",
  init = function()
    vim.g.vimtex_view_method = "zathura" -- 按你的PDF阅读器改：skim、okular、sumatrapdf等
    vim.g.vimtex_compiler_method = "latexmk"
    vim.g.vimtex_compiler_latexmk = { options = { "-pdf", "-shell-escape", "-interaction=nonstopmode" } }
    vim.g.vimtex_syntax_enabled = 0
    vim.g.vimtex_fold_enabled = 0
    vim.g.vimtex_quickfix_mode = 0
  end,
  config = function()
    vim.keymap.set("n", "<localleader>lt", ":VimtexTocToggle<CR>", { buffer = true })
    vim.keymap.set("n", "<localleader>lv", ":VimtexView<CR>", { buffer = true })
  end,
}

latexmk是默认的编译工具，会自动处理多遍编译、参考文献、交叉引用。-shell-escape在某些宏包（比如minted）需要时会用到，如果不需要可以去掉。-interaction=nonstopmode的作用是遇到错误不弹交互提示，直接写日志，方便在quickfix里看。

texlab的接入：

lua复制{
  "neovim/nvim-lspconfig",
  dependencies = {
    "hrsh7th/cmp-nvim-lsp",
    "williamboman/mason.nvim",
    "williamboman/mason-lspconfig.nvim",
  },
  config = function()
    local lspconfig = require("lspconfig")
    lspconfig.texlab.configure = nil
    require("mason-lspconfig").setup_handlers({
      ["texlab"] = function()
        lspconfig.texlab.setup({
          capabilities = require("cmp_nvim_lsp").default_capabilities(),
          settings = {
            texlab = {
              build = { onSave = true, executable = "latexmk", args = { "-pdf", "-interaction=nonstopmode" } },
              chktex = { onOpenAndSave = true, onEdit = false },
            },
          },
        })
      end,
    })
  end,
}

这里的onSave = true表示保存时自动编译，chktex可以在写文档时检查一些常见的LaTeX排版错误（比如$...$内部的空格问题、引号方向问题）。这些属于“职业级”的检查，虽然偶尔会误报，但总体能帮你减少很多低级错误。

5.3 正向搜索和反向搜索

最后提一个很多人问的配置点：正向搜索，就是在Neovim里按快捷键，跳到PDF对应位置。这个功能由vimtex提供，通过VimtexView触发。前提是PDF阅读器支持SyncTeX，并且vimtex的view_method配置正确。

常见的组合是Linux用Zathura、macOS用Skim、Windows用SumatraPDF。这三者的配置我都试过，体验最好的是Zathura（打开速度快、快捷键顺手），但Skim和SumatraPDF也完全够用。重点提醒：要确保你的LaTeX编译命令开启了-synctex=1，latexmk默认会加这个参数，但如果你改过编译器方法，就得注意一下。

反向搜索就是从PDF点击跳回Neovim，需要在阅读器里配置对应命令。以Skim为例，它的预设可以直接在Neovim里通过:help vimtex-view查到；Zathura需要在配置里设置synctex相关的回调。这个配置虽然有点绕，但一旦配好，查文档、改错位、调整公式的效率会高一大截。

6. 写在最后的体会

说实话，配置这套东西最花时间的不是安装，而是理解tree-sitter的节点结构、以及想明白哪个插件该负责什么。我最初踩过的坑就是所有插件都开着全部功能，结果vimtex、tree-sitter、texlab三者在高亮和折叠上打架，文档打开都卡。后来理清分工、关掉重复功能，整个环境才真正稳定下来。

如果你刚开始配置，我的建议是分三步走：先把tree-sitter的latex parser装好，确认默认高亮ok；再加textobjects，体验一下基于环境的选择操作；最后再接入vimtex和texlab，把编译和补全补齐。别急着一次抄全配置，否则出问题你都不知道是自己写错还是插件冲突。

实际用下来，我最依赖的三个操作是：cie改整个环境内容、:VimtexView看PDF、texlab的自动补全。这三个都离不开tree-sitter打下的语法分析基础。对我来说，这套环境已经足够支撑日常写论文和做笔记，不再需要为了LaTeX专门打开其他编辑器。