企业官网建设流程全解析

1. 问题本质：中文、数学与代码高亮为什么会“打架”

先说结论：困扰很多 LaTeX 用户的“中文和数学代码同时高亮”问题，本质上不是 LaTeX 本身不支持，而是编辑器与编译器两层协同的问题。

很多人在刚开始用 LaTeX 时，都是从 TeXworks 或者 WinEdt 这类老牌编辑器入手的。这些编辑器对中文的支持非常“原生”——没错，你能正常输入中文，甚至能编译出中文 PDF，但当你写数学公式时，编辑器里一片黑，没有高亮；当你插入代码块时，更是完全没有语法着色。这种体验在写大文档时非常折磨，尤其是需要频繁在中文叙述、数学公式、代码示例三者之间切换的场景，一旦失去高亮，找错、改错、排版调整的效率会明显下降一个台阶。

要理解这个问题，得先拆开 LaTeX 的工作链路。LaTeX 文档从.tex源文件变为 PDF，需要经过“编辑器编写 → 编译器编译 → 引擎渲染”三个环节。高亮发生在编辑器环节，也就是你写代码时屏幕上看到的颜色；中文渲染发生在引擎环节，通常是 xelatex 配合 ctex 宏包或者 fontspec 方案；代码块高亮发生在编译环节，由 minted 或 listings 宏包在生成 PDF 时对代码进行着色。三层各管各的，但如果搭配不当，中文显示、数学高亮、代码着色三者就会互相干扰。

1.1 三套高亮规则都没有协同设计

我做过一个不太严谨但很形象的类比：你在一间昏暗的房间里，左手拿一盏只能照中文的台灯，右手拿一盏只能照英文的台灯，背后还有一盏只能照数字的路灯。三束光都是亮的，但永远照不全整个桌面。

这就是当前编辑器生态的普遍状态。老牌 LaTeX 编辑器（TeXworks、WinEdt、TeXstudio）里的“高亮”概念通常只针对 LaTeX 命令关键字（\begin、\frac、\textbf等），数学环境（$...$、\[...\]、align等）虽然也能识别，但公式内部的字母、符号并不会像现代 IDE 那样智能着色。更麻烦的是，当你引入中文后，很多编辑器的语法高亮引擎对 CJK 字符的处理优先级很低——中文文本不会进入任何高亮规则，只有标点符号会被误判为 LaTeX 命令的一部分，于是整个文档的高亮就变得混乱。

而另一头，代码块高亮的主力方案minted宏包，后端依赖 Python 的 Pygments 库。它在编译时会把代码片段渲染成带颜色的文本嵌进 PDF，但它和编辑器里的高亮没有任何关系。也就是说，即使你编译出的 PDF 里代码颜色非常漂亮，你编辑.tex源文件时，看到的一段\begin{minted}{python}与\end{minted}包裹的代码，依然可能是清一色的黑底白字（或者白底黑字）。两个“高亮”不在同一个维度上，自然给人一种“同时支持中文和数学代码高亮很难”的错觉。

1.2 选对工具链：VS Code 是当前最优解

在反复试过多个编辑器和方案后，我把组合最终确定为：TeX Live + VS Code + LaTeX Workshop + minted/XeLaTeX。这个组合在“编辑体验”和“编译输出”两端都做到了比较理想的高亮效果。

• VS Code 的语法高亮引擎非常成熟，而且支持用户自定义 TextMate 规则。只要装好 LaTeX Workshop 插件，.tex文件里的中文、数学环境、命令关键字都能获得比较舒服的视觉分区。
• 编译走 xelatex 引擎，中文字体问题一次解决，不需要折腾 GBK/UTF-8 编码转换。
• 代码块在 PDF 里用 minted 渲染，在编辑器里则保持普通文本，但 LaTeX Workshop 提供了不错的缩进和括号匹配，配合颜色主题，整体观感已经接近专业 IDE。

如果你用的还是老派编辑器，也不用急着换。但有一点必须明白：不要指望一个纯 LaTeX 编辑器把“中文+数学+代码”三套高亮同时做得很好，它们的架构里没有为中文这一层语法做足够的扩展支持，硬调也是事倍功半。VS Code 是目前所有方案里，扩展成本最低、可控性最强的选择。

1.3 引擎选型：为什么必须是 XeLaTeX

高亮问题绕不开中文渲染，而中文渲染又绕不开编译器引擎。很多新手拿到的模板默认是 pdfLaTeX 编译，这时候你写中文，运气好能通过\usepackage[UTF8]{ctex}硬撑一下，但稍微遇到用户自定义字体或者特殊符号就崩。

如果你要在文档里同时处理中文、数学公式、代码三件事，我的建议很直接——直接用 XeLaTeX 引擎，别在 pdfLaTeX 上浪费时间。

原因很简单：XeLaTeX 原生支持 UTF-8 和系统字体，配合ctex宏包或者直接调用fontspec，中文字体选择和字形渲染都比较稳妥。数学公式方面，XeLaTeX 与amsmath、amssymb的兼容性完全没问题。代码块方面，minted 宏包和各种现代方案也都是为 XeLaTeX 做了完整支持的。

提示：如果你在写文档时发现“中文能显示但数学符号显示不出来，或者代码块一编译就报错”，十有八九是因为你用的是 pdfLaTeX 引擎，先把引擎换成 XeLaTeX，再继续排查后面的事情。

2. 环境配置：从编译器到编辑器的完整链路

高亮不是单独配置哪一项就能解决的，我建议按照“编译器 → 编辑器 → 宏包 → 最小示例”这个顺序一步步验证。每一步都有它对应的坑，一次性全部配置完再调试，出了问题不好定位。

2.1 TeX 发行版选择与安装验证

Windows 上推荐 TeX Live，macOS 上推荐 MacTeX（本质是 TeX Live 的 macOS 发行版），Linux 上直接通过包管理器安装texlive-full也省事。不建议用 CTEX 套装，它已经很久不更新了，对新宏包的支持不太够。

安装完成后，打开命令行工具，依次执行以下命令来确认核心组件是否就位：

xelatex --version pygmentize --version

pygmentize是 minted 宏包的后端工具，如果你没有单独装 Python 环境，大概率会在这里报“命令未找到”。解决方法是安装 Python（建议 3.8 以上版本），然后执行pip install pygments。安装完成后重新执行pygmentize --version，看到版本号就说明环境准备就绪了。

pip install pygments

这个步骤很关键，但很多人会忽略，导致后面写\begin{minted}{python}时编译一直报错“You must havepygmentizeinstalled to use this package”，折腾半天才发现是 Python 环境的问题。

2.2 VS Code + LaTeX Workshop 的推荐配置

VS Code 里安装 LaTeX Workshop 插件后，默认情况下它就能识别.tex文件，并调用 LaTeX 命令进行编译。但默认配置不一定适合中文+数学+代码的混合文档，我建议直接按下图方向修改用户设置。打开 VS Code 的settings.json，把下面这份配置粘贴进去：

{ "latex-workshop.latex.recipes": [ { "name": "xelatex", "tools": ["xelatex"] }, { "name": "xelatex-minted", "tools": ["xelatex-minted"] } ], "latex-workshop.latex.tools": [ { "name": "xelatex", "command": "xelatex", "args": [ "-synctex=1", "-interaction=nonstopmode", "-file-line-error", "-pdf", "%DOC%" ] }, { "name": "xelatex-minted", "command": "xelatex", "args": [ "-synctex=1", "-interaction=nonstopmode", "-shell-escape", "-file-line-error", "-pdf", "%DOC%" ] } ], "latex-workshop.view.pdf.viewer": "tab" }

其中的xelatex-minted配方专为使用 minted 宏包的文档准备。重点在于-shell-escape参数，minted 需要在编译过程中调用外部 Python 命令行工具，默认情况下 TeX 编译器出于安全考量会禁用这种操作，必须显式加上-shell-escape才能放行。如果你不用 minted，那么普通配方就够用，拉满-shell-escape反而有潜在的安全风险。

2.3 中文字体配置的三种方式

在编辑器层面把高亮规则调好之后，还得保证编译输出能正常显示中文，否则一切白搭。当前主流的方案有两种：

第一种是直接用ctex宏包，这也是目前最简单的中文方案：

\documentclass[UTF8]{ctexart}

或者你用的是标准article文档类，可以这样引入：

\documentclass{article} \usepackage[UTF8]{ctex}

ctex宏包会自动检测当前操作系统，调用系统中已有的中文字体来渲染，基本做到零配置。缺点是你对具体字体的控制能力相对有限。

第二种是用fontspec配合xeCJK宏包，适合对字体有定制需求的场景：

\usepackage{fontspec} \usepackage{xeCJK} \setCJKmainfont{宋体} \setmainfont{Times New Roman}

这里\setCJKmainfont指定的是中文主字体，\setmainfont指定的是西文主字体。在 macOS 上你可能会想把“宋体”换成“STSong”或者“PingFang SC”，在 Windows 上则是“宋体”或“微软雅黑”比较常见。选择哪种方案取决于你对字体控制的需求，如果只是写作业、论文、报告，ctex完全够用；如果是书籍排版或者品牌视觉要求比较高，建议用xeCJK手动指定字体。

补充一个容易踩的坑：如果你的文档是通过\documentclass{article}创建的，然后又通过\usepackage[UTF8]{ctex}引入中文支持，那么必须注意不要同时使用fontspec和ctex里重复的字体设置轮子，否则很容易出现字体警告甚至编译失败。

2.4 最简示例：一键验证中文和数学

配置完成后来一个最小验证。新建一个test.tex文件，写入以下内容，然后用 LaTeX Workshop 的“Recipe: xelatex”编译，看是否能正常生成 PDF：

\documentclass[UTF8]{ctexart} \usepackage{amsmath} \begin{document} \section{中文与数学公式测试} 这是一个包含中文的文档。下面是一个数学公式： \begin{equation} E = mc^2 \end{equation} 行内公式也有，比如 $\alpha + \beta = \gamma$。 \end{document}

如果 PDF 能正常显示中文、公式也能正确渲染，说明整条链路没问题。如果中文显示成乱码或者方块，那基本是字体或引擎的问题，请先检查编译日志里是否出现了xelatex被替换成pdflatex的情况，以及系统里是否有可用的中文字体。

3. 编辑器内的数学公式高亮：原理与自定义

解决了“能编译”的问题，接下来才进入真正的“高亮体验”阶段。编辑器内的高亮分为两层：一层是 VS Code 自带的 TextMate 语法高亮，负责识别 LaTeX 命令、注释、数学环境等；另一层是 LaTeX Workshop 组件提供的更多上下文识别。这里重点说数学公式高亮怎么让它变得更好用。

3.1 为什么默认的数学高亮不够用

VS Code 默认对 LaTeX 的数学环境是能识别的。当你输入$...$或\[...\]时，它会用同一种颜色标出公式区块里的内容。问题在于，公式内部不同元素（变量、数字、运算符、希腊字母）用的是同一套颜色，在复杂公式里视觉区分度很低。

举个例子，下面这段公式在高亮不精细时，所有字母都是一个颜色，很难一眼看出哪个是向量、哪个是标量：

\begin{align} \mathbf{F} &= m \mathbf{a} \\ E_k &= \frac{1}{2} m v^2 \end{align}

如果你希望\mathbf加粗的向量符号、希腊字母\alpha、数字符号能显示成不同颜色，则需要自定义 TextMate 规则。LaTeX Workshop 实际上自带了不少作用域定义（scope），比如constant.character.math.tex、variable.parameter.math.tex等，但默认颜色主题对这些作用域的处理并不统一，所以需要微调。

3.2 自定义数学高亮规则的实操方法

以 VS Code 默认的深色主题（Dark+）为例，打开设置，搜索editor.tokenColorCustomizations，然后把你想要调整的作用域添加进去：

{ "editor.tokenColorCustomizations": { "textMateRules": [ { "scope": "constant.character.math.tex", "settings": { "foreground": "#d19a66" } }, { "scope": "variable.parameter.math.tex", "settings": { "foreground": "#61afef" } }, { "scope": "support.function.math.tex", "settings": { "foreground": "#c678dd" } } ] } }

这三条规则分别把数学环境里的常量字符（数字）、变量参数、函数关键字做了颜色区分。实际效果因主题而异，你完全可以根据自己的色觉偏好调整色值。除此之外，打开 LaTeX Workshop 的设置项latex-workshop.intellisense和latex-workshop.hover.preview，还能在鼠标悬停到数学命令上时预览公式效果，对排查公式错误有很大帮助。

要查看某个字符当前被分配了什么作用域，VS Code 里有一个非常实用的方式：把光标放在这段字符上，然后打开命令面板（Ctrl+Shift+P），执行“Developer: Inspect Editor Tokens and Scopes”，就能看到这个字符被识别成哪些作用域。掌握了这个手段，你就能精准地针对某个高亮问题做定向修改，不用盲猜乱试。

3.3 中文与数学混排时的高亮协调

中文和数学混排的场景下，还有一个容易忽略的视觉问题：中文文字的颜色与数学符号的颜色如果不适当地协调，页面看起来会显得杂乱。

建议在配置高亮时，遵循一个简单的配色原则——中文文字保持编辑器默认的前景色，数学符号采用与默认前景色有明显区分但饱和度不要太高的颜色。我实测下来，比较舒服的组合是中文文字用近白色（在深色主题下），变量用淡蓝色（#61afef），数字用琥珀色（#d19a66），运算符保持默认的粉色或白色。这样既能区分数学和正文，又不会像花坛一样乱。

我这里给出的只是个人常用的色调，关键是你要理解：高亮规则是分层的，颜色的设置不是为了“好看”，而是为了让人眼能快速定位特定类型的符号。你完全可以按自己的习惯改，只要遵循“同类元素同色、异类元素不同色”的原则即可。

4. PDF 里代码块的高亮：minted 完整配置

如果说编辑器内的高亮是“写代码时的体验”，那 PDF 内代码块的高亮就是“成品文档的阅读体验”。很多人希望最终生成的 PDF 里，粘贴的 Python、Java、C++ 代码也有类似 IDE 里的配色，这件事在 LaTeX 里主要通过两个宏包实现：minted和listings。

4.1 minted 与 Pygments 的关系

minted宏包本身并不负责颜色渲染，它实际上是一个“搬运工”：在编译时，它会把代码块内容提取出来，交给 Python 的 Pygments 库做词法分析和高亮，再把分析结果以 LaTeX 命令的形式插入到文档里。

这意味着三件事：

• 系统里必须安装 Python 环境和 Pygments 库
• 编译时必须开启-shell-escape参数，否则 minted 没有权限调用外部命令
• 如果你换了一台电脑编译同一个文档，必须确保那台电脑也装了 Pygments

minted 支持上百种编程语言的语法高亮。常用的语言比如 Python、Java、C++、JavaScript、Bash、SQL、JSON、HTML、CSS，基本都是开箱即用。你不需要记住每种语言的关键字规则，Pygments 已经帮你处理好了，这也是它比listings更省心的原因。

4.2 完整示例：从导言区到正文

来看一个能直接复制使用的完整配置：

\documentclass[UTF8]{ctexart} \usepackage{amsmath} \usepackage{minted} % minted 样式设置 \usemintedstyle{default} \setminted{ breaklines=true, breakautoindent=false, fontsize=\small, frame=single, framesep=6pt, tabsize=4, autogobble=true } \begin{document} \section{代码块示例} 下面是一段 Python 代码： \begin{minted}{python} import numpy as np def compute_energy(mass, velocity): """ 计算动能 """ return 0.5 * mass * velocity ** 2 result = compute_energy(10, 3) print(result) \end{minted} \end{document}

这里我解释几个参数的含义：

• breaklines=true：当代码某一行过长时，允许自动换行。如果不开启，长代码超出页面边界时会被直接截断，非常难看。
• autogobble=true：自动去除代码块左侧的公共缩进。这个功能很实用，因为你在.tex文件里写代码时通常会有排版缩进（比如在\begin{minted}前面有两个 tab），开启后 minted 会自动把这段公共缩进去掉，保证渲染出的代码顶格，和你在独立代码编辑器中看到的效果一致。
• frame=single：给代码块加一个边框，视觉上更清晰。如果你的文档风格比较极简，也可以设为frame=none。
• fontsize=\small：代码字体略小于正文，显得更精致。如果你的代码较长，可以用\footnotesize进一步缩小。

编译时，在 VS Code 里点击 LaTeX Workshop 的“Recipe: xelatex-minted”即可，或者直接在命令行执行：

xelatex -shell-escape -interaction=nonstopmode -file-line-error -pdf test.tex

如果编译顺利，你会在生成的 PDF 中看到带语法高亮的代码块，和 IDE 里的效果非常接近。

4.3 切换代码高亮样式：Pygments 主题

minted 默认使用 Pygments 的default样式。如果你想换成其他配色，可以通过\usemintedstyle来调整：

\usemintedstyle{vs} \usemintedstyle{friendly} \usemintedstyle{colorful} \usemintedstyle{xcode}

想要知道系统支持哪些主题，可以在命令行执行：

pygmentize -L styles

你会看到几十个主题名称。有些主题适合浅色背景（如friendly、vs），有些适合深色背景（如monokai、native）。选择主题时，请务必与你\pagecolor或文档背景色配合。如果你用的是白纸黑字的论文模板，用friendly或default就足够；如果是做 PPT 或带深色背景的演示文档，那monokai更合适。

我个人的偏好是friendly，它对中文注释的显示比较友好，各颜色区块的对比度适中，打印出来也不会过于刺眼。

4.4 listings 的替代方案

如果你因为某些原因无法安装 Python 环境，listings宏包可以作为备选。它不依赖外部工具，纯 TeX 实现，兼容性极好。但它的语法高亮能力相对有限，需要自己指定关键字列表：

\usepackage{listings} \lstset{ language=Python, basicstyle=\ttfamily\small, keywordstyle=\color{blue}, commentstyle=\color{gray}, stringstyle=\color{red}, showstringspaces=false } \begin{lstlisting} def hello(): print("Hello, world!") \end{lstlisting}

这在高亮精度、代码换行、中文注释支持上都比 minted 弱一些。如果你的文档中代码量不大，用listings也能应付；如果经常贴各种语言的代码且换行频繁，还是建议直接将 minted 作为主力。

5. 三合一大实战：中文、数学、代码同页高亮

把前面几个部分串起来，就能拼出一个完整的、中文与数学和代码同时高亮的 LaTeX 文档。这一节我给出一个综合示例，并解释其中的排版调优细节。

5.1 一个完整的综合示例

\documentclass[UTF8]{ctexart} \usepackage{amsmath} \usepackage{minted} \usepackage{xcolor} \usemintedstyle{friendly} \setminted{ breaklines=true, breakautoindent=false, fontsize=\small, frame=single, framesep=6pt, tabsize=4, autogobble=true, python3=true } \begin{document} \section{综合示例} 中文正文部分可以正常显示，下面是一个行内公式：$\alpha + \beta = \gamma$。 \begin{equation} \int_0^\infty e^{-x^2} \, dx = \frac{\sqrt{\pi}}{2} \end{equation} 接着是一段 Python 代码： \begin{minted}{python} import numpy as np # 计算圆周率近似值 def estimate_pi(n): points = np.random.rand(n, 2) inside = np.sum(points[:, 0]**2 + points[:, 1]**2 <= 1) return 4 * inside / n print(estimate_pi(100000)) \end{minted} 以上就是完整的排版示例。 \end{document}

编译命令不变，仍然用 xelatex +-shell-escape。编译之后你观察这几个位置：中文是否正常显示、公式是否居中且编号正常、代码是否有高亮且边框整齐。如果每一项都没问题，说明你的工具链路已经完整串起来了，以后写文档会遇到的最大障碍已经解除。

5.2 高亮配色与文档整体风格的协调

这里有个细节值得展开说说。minted 的代码块背景色默认是白色（或透明的），如果你在文档中使用了自定义的页边背景色，需要同步调整 minted 的背景色，否则代码块会显得突兀。可以在\setminted中加上bgcolor参数：

\setminted{ bgcolor=lightgray!20 }

lightgray!20表示 20% 强度的浅灰色。在实际项目中，为了配合出版或打印需求，我也会用bgcolor=gray!15或者干脆不加背景色只保留边框。记住一个原则：代码高亮的目的是让代码在文档中清晰可辨，而不是让代码块成为整个页面的视觉焦点，所以背景、边框、字号的设置都应该尽量克制。

数学公式的配色方面，如果你的文档里用了大量带颜色的公式（比如用\textcolor突出某些推导步骤），那么建议与代码高亮的颜色保持同一色系，避免产生“文档头部和尾部风格不一致”的观感。

5.3 中文与代码混排的间距和换行问题

最后一个值得注意的体验细节：中文与代码混排时，行内代码（比如你在正文里写“执行pip install pygments”）的排版。最简单的方式是用 LaTeX 默认的\texttt{}：

执行 \texttt{pip install pygments} 安装依赖。

这样在 PDF 中会出现等宽字体样式，和正文的中文字体形成对比，清晰可辨。如果你想在行内代码中也加入语法高亮，可以借助\mintinline命令：

执行 \mintinline{bash}{pip install pygments} 安装依赖。

\mintinline是 minted 提供的行内代码高亮命令，它可以在正文句子中直接对一段短代码进行语法着色，效果和独立代码块保持一致。这个功能对技术文档非常友好，推荐多用。

不过\mintinline对中文注释的支持在个别 Pygments 主题下会有小问题，如果发现行内代码块中的中文显示异常，一个简单的退路是把它改成\texttt{}，不再追求行内高亮。

6. 常见问题与实际排查：关于高亮和中文，我踩过的那些坑

配置过程中会遇到很多报错或异常现象，绝大多数不是某个单一原因造成的，而是多个环节叠加所致。这里把我踩过的坑按最常见、最容易误判的顺序整理一遍，方便快速定位问题。

6.1 常见问题速查表

6.2 minted 中文注释乱码的详细处理

这是一个高频问题。很多人在 minted 代码块里写中文注释，编译出的 PDF 中注释汉字显示成乱码或问号。出现这个问题的原因通常是Pygments 源码解析时对字符编码处理不当，或者文档字体没有设置好中文字体。

首先确认你的编译引擎是 xelatex，并且导言区已经配置好中文字体（ctex或xeCJK）。然后确认 Pygments 版本较新，旧版本对 Unicode 的支持有缺陷：

pip install --upgrade pygments

如果升级后仍不行，尝试在 minted 设置里指定编码：

\usepackage[utf8]{inputenc}

虽然 xelatex 下inputenc的作用有限，但配合某些模板不会出问题。再不行，就把\setminted的样式切换到friendly或xcode，这两个样式对中文注释的渲染相对稳定。

6.3 编辑器里中文高亮消失的几种解法

VS Code 中，中文默认是能被识别为普通文本的，不会像英文变量名那样有独立颜色。如果你希望中文在视觉上和英文文本区分开，可以通过修改主题的工作区颜色实现：在settings.json中添加：

{ "editor.tokenColorCustomizations": { "textMateRules": [ { "scope": "comment", "settings": { "foreground": "#6a9955" } } ] } }

comment作用域会把所有注释（包括看中文注释）都染成绿色，这样当你扫视文档时，中文注释一眼就能辨认出来。如果你希望正文中的中文也有特殊颜色，那就需要改造 TextMate 语法规则，普通用户不建议折腾这一层，收益不大且容易引入新的颜色混乱。

6.4 一个容易被忽略的 “高亮主次” 原则

配置到最后，我想提醒一个容易被忽略的原则：高亮是为了信息分层，不是为了炫技。

我在早期配高亮方案时，恨不得每个花括号都带一种颜色，结果写文档时眼睛全花，反而找不到重点。后来调整策略，只保留三层视觉强调：

• 正文和中文叙述保持默认色（低信息量层级）
• 数学环境和代码块用中等对比的颜色（中等信息量层级）
• 错误提示、编译警告用高亮颜色（高信息量层级）

这样下来，整个文档的扫读体验反而好得多。你在配置高亮时，不妨也按这个原则走：先把基础链路跑通，再针对自己的使用频率调整颜色细节，不必一上来就追求“五彩斑斓”。

最后分享一个小技巧

如果需要在同一个文档里大量处理中文和代码，建议在.latexmkrc文件里固化编译参数，避免每次手动加-shell-escape。在项目根目录新建一个名为.latexmkrc的文件，写入：

$xelatex = 'xelatex -shell-escape -interaction=nonstopmode -file-line-error -pdf %O %S';

这样在 VS Code 里直接使用 LaTeX Workshop 默认的“Recipe: latexmk”也能自动带上-shell-escape参数，minted 和中文都能正常处理。这个小改动节省了我大量的重复工作，希望对你也同样有用。