1. 从“代码块”到“专业排版”为什么listings宏包是LaTeX用户的必备工具在撰写技术文档、学术论文或者实验报告时我们常常需要插入一段代码。很多新手的第一反应可能是直接复制粘贴或者用截图的方式贴上去。这样做在Word里或许能应付但在追求极致排版质量和专业性的LaTeX世界里就显得非常业余了。代码的字体、缩进、高亮、行号这些细节直接决定了读者阅读代码的体验也侧面反映了文档作者的专业程度。LaTeX本身并没有原生的、功能强大的代码排版命令。虽然你可以用\texttt{}把代码变成等宽字体或者用verbatim环境保留空格和换行但这仅仅是“能看”离“好看”和“好用”还差得远。这时listings宏包就登场了。它不是一个可选项而是几乎所有需要展示代码的LaTeX用户的标准配置。它让你能像在专业的IDE比如WebStorm、VS Code里一样为代码设置语法高亮、自动添加行号、设置代码框、甚至定义自己的关键字和注释样式。简单来说listings宏包解决的核心问题是如何在LaTeX文档中以出版级的印刷质量清晰、美观、可定制地展示程序源代码。无论你是计算机专业的学生在写课程报告研究员在撰写包含算法伪代码的论文还是工程师在制作技术手册掌握listings都是提升文档质感的关键一步。接下来我将结合多年的排版经验带你从零开始彻底搞懂这个强大工具的使用、定制和那些官方手册里不会写的“坑”。2. 基础入门快速创建一个带高亮的代码块让我们先抛开所有复杂的配置看看如何用最少的代码实现一个可用的、带基础高亮的代码块。这是你迈出的第一步。2.1 宏包的引入与最小化示例首先你需要在文档的导言区\begin{document}之前引入listings宏包。通常我们会同时引入xcolor宏包来为高亮提供颜色支持。\documentclass{article} \usepackage{xcolor} % 提供颜色支持 \usepackage{listings} % 代码高亮宏包 \begin{document}引入之后你就可以使用lstlisting环境来插入代码了。最基本的用法如下\begin{lstlisting}[languagePython] def hello_world(): # 这是一个简单的Python函数 print(Hello, LaTeX listings!) return 0 \end{lstlisting}编译后你会得到一个等宽字体显示的Python代码块注释和关键字可能还没有颜色但缩进和结构已经非常清晰了。这里的languagePython是关键参数它告诉listings按Python的语法规则来解析这段代码为后续的高亮打下基础。支持的语言非常多常见的有C,Java,JavaScript,Matlab,TeX等等你可以在官方文档中找到完整的列表。2.2 第一个可用的“主题”配置为了让代码看起来更像我们在编辑器里习惯的样子我们需要定义一个基本的样式。我习惯在导言区定义一个名为mystyle的样式这样可以在全文多次复用。\usepackage{xcolor} \usepackage{listings} \definecolor{codegreen}{rgb}{0,0.6,0} \definecolor{codegray}{rgb}{0.5,0.5,0.5} \definecolor{codepurple}{rgb}{0.58,0,0.82} \definecolor{backcolour}{rgb}{0.95,0.95,0.92} \lstdefinestyle{mystyle}{ backgroundcolor\color{backcolour}, % 设置背景色 commentstyle\color{codegreen}, % 注释样式 keywordstyle\color{magenta}, % 关键字样式 numberstyle\tiny\color{codegray}, % 行号样式 stringstyle\color{codepurple}, % 字符串样式 basicstyle\ttfamily\footnotesize, % 基本字体样式 breakatwhitespacefalse, % 只在空格处断行 breaklinestrue, % 自动换行 captionposb, % 标题位置在底部 keepspacestrue, % 保持空格 numbersleft, % 行号在左边 numbersep5pt, % 行号与代码的距离 showspacesfalse, % 不显示空格标记 showstringspacesfalse, % 字符串中不显示空格标记 showtabsfalse, % 不显示制表符标记 tabsize4 % 制表符等效空格数 } \lstset{stylemystyle} % 将此样式设为全局默认这段配置定义了一个浅灰色背景、绿色注释、洋红色关键字、紫色字符串的样式并开启了行号和自动换行。现在你在文档中任何地方使用lstlisting环境都会自动套用这个美观的样式。\begin{lstlisting}[languagePython] # 现在这段代码就有高亮了 import numpy as np def calculate_mean(data): 计算数据的平均值 return np.sum(data) / len(data) if len(data) 0 else 0 \end{lstlisting}注意颜色定义\definecolor是非常个人化的一步。你可以根据文档的整体配色方案进行调整。网上有很多流行的配色方案如 Solarized, Monokai你可以搜索其RGB值直接使用。basicstyle中的\ttfamily代表等宽字体\footnotesize控制字号这是保证代码可读性的基础。3. 深度定制打造属于你的IDE级高亮效果基础的配置只能满足“有颜色”的需求。但如果你想让LaTeX里的代码看起来和你心爱的VS Code或WebStorm主题一模一样或者需要对特定语法元素进行精细控制就需要深入listings的定制功能。这部分是区分“会用”和“精通”的关键。3.1 关键字、注释与字符串的精细控制listings将代码元素分为几个大类关键字keywords、注释comments、字符串strings、标识符identifiers等。我们可以为每一类甚至每一个子类单独设置样式。1. 添加更多关键字像Python的print,len,np作为numpy的常用别名可能不在默认关键字列表中。我们可以手动添加\lstdefinestyle{myPythonStyle}{ languagePython, morekeywords{print, len, np, pd, plt}, % 添加自定义关键字 keywordstyle\color{blue}\bfseries, % 关键字样式蓝色粗体 commentstyle\color{gray}\itshape, % 注释样式灰色斜体 stringstyle\color{orange}, % 字符串样式橙色 alsoletter{\#}, % 将#也视为字母以便高亮#开头的注释 }2. 区分不同注释类型在有些语言中单行注释和多行注释的符号不同。listings可以分别处理\lstdefinestyle{myCStyle}{ languageC, morecomment[l]{//}, % [l]代表line-comment即行注释 morecomment[s]{/*}{*/}, % [s]代表delimited-comment即界定符注释 commentstyle\color{green!50!black}, % 统一注释颜色也可分别定义 }3. 处理特殊字符串和转义字符对于包含特殊字符如LaTeX命令的字符串需要小心处理防止被LaTeX编译。listings提供了literate参数进行字符替换。\lstdefinestyle{myTeXStyle}{ language[LaTeX]TeX, literate % 字面值替换将左侧字符在输出时替换为右侧并应用指定的样式 {\{}{{\textcolor{red}{\{}}}1 % 将 { 替换为红色的 {1代表一个字符位 {\}}{{\textcolor{red}{\}}}}1 {\$}{{\textcolor{green}{\$}}}1 {\_}{{\textcolor{blue}{\_}}}1, basicstyle\ttfamily\small, }这个配置在展示LaTeX代码本身时非常有用能将{,},$,_等特殊字符高亮显示既美观又避免了编译冲突。3.2 边框、背景与浮动体让代码块成为文档的亮点一个孤零零的代码块在文档中可能显得突兀。通过添加边框、标题并将其放入浮动体可以让它像图表一样被自动编号和引用成为文档中真正的“亮点”。1. 添加边框和阴影listings本身边框功能有限但我们可以结合tcolorbox或mdframed宏包实现惊艳的效果。这里以tcolorbox为例它功能强大且与listings集成良好。\usepackage[most]{tcolorbox} % 导入tcolorbox宏包 \tcbuselibrary{listings, skins, breakable} % 定义一个漂亮的代码环境 \newtcblisting{mylisting}[2][]{ % #1为可选参数#2为语言 listing only, % 只包含代码列表 listing options{stylemystyle, language#2}, % 应用listings样式 colbackbackcolour, % 背景色 colframeblack!75!white, % 边框颜色 arc3pt, % 圆角半径 title代码 \thetcbcounter: #1, % 自动编号的标题 fonttitle\bfseries, breakable, % 允许跨页 enhanced, % 启用增强功能 drop fuzzy shadow, % 添加阴影 attach title to upper, % 标题紧贴内容 before skip10pt, after skip10pt, % 前后间距 }在文档中使用\begin{mylisting}[一个Python函数示例]{Python} def factorial(n): if n 1: return 1 else: return n * factorial(n-1) \end{mylisting}这样生成的代码块拥有圆角边框、阴影、自动编号的标题视觉效果和专业书籍中的代码片段无异。2. 使用浮动体与标题如果你希望代码块像图、表一样可以“浮动”到合适的位置并拥有“图X.X”或“代码X.X”这样的标题可以使用\lstlistoflistings和\lstinputlisting配合caption和label。首先在导言区设置代码浮动体的标题名称\renewcommand{\lstlistingname}{代码} % 将默认的Listing改为中文代码 \renewcommand{\lstlistlistingname}{代码索引} % 代码目录的标题在文档中插入一个可浮动的、带标题的代码\begin{lstlisting}[languagePython, caption{计算斐波那契数列的函数}, labelcode:fib, floathtbp] def fibonacci(n): a, b 0, 1 for _ in range(n): a, b b, a b return a \end{lstlisting}这里floathtbp参数允许代码块浮动位置偏好为 here, top, bottom, page。你可以像引用图一样引用它如代码\ref{code:fib}所示。在文档末尾使用\lstlistoflistings命令可以生成所有代码的索引目录。实操心得对于较短的、希望紧跟在正文后的代码可以不使用float参数。对于较长或位置不敏感的代码使用浮动体并添加caption是更专业的选择便于管理和交叉引用。使用tcolorbox包装后浮动体功能可能会受限需根据美观和功能的优先级进行权衡。4. 高级技巧与实战排坑指南掌握了基本和进阶功能后在实际写作中你一定会遇到一些棘手的问题。下面这些技巧和“坑”都是我从无数次编译错误和排版调整中总结出来的能帮你节省大量时间。4.1 处理“Invalid UTF-8 byte sequence”等编码错误这是一个非常常见的错误尤其当你从Windows系统复制代码或者代码文件中包含中文注释时。错误信息通常是LaTeX Error: Invalid UTF-8 byte sequence。根因分析LaTeX的listings宏包默认将代码内容当作纯文本ASCII处理。当它遇到UTF-8编码的中文、特殊符号如全角空格、破折号时会因为无法识别这些多字节字符而报错。解决方案你需要显式地告诉listings输入文件的编码并启用对Unicode字符的处理。对于直接在.tex文件中编写的lstlisting环境 在文档导言区或样式设置中添加inputencodingutf8和texcltrue参数。\lstset{ inputencodingutf8, % 输入编码为UTF-8 extendedcharstrue, % 允许扩展字符集 texcltrue, % 将注释中的LaTeX代码也进行解析慎用见下文 % 或者使用更安全的 mathescapefalse, literate 处理中文 }对于中文注释更稳妥的方法是使用literate参数进行转义或者干脆避免在lstlisting环境内直接写中文。可以将中文注释写在caption或周围的正文中。对于通过\lstinputlisting引入的外部代码文件 确保你的.tex文件本身以UTF-8无BOM格式保存这是现代编辑器的默认设置。然后在引入时指定编码\lstinputlisting[ languagePython, caption{外部Python文件}, inputencodingutf8 ]{./code/my_script.py}终极排查步骤检查你的代码文件用VS Code、Notepad等编辑器打开确保底部状态栏显示“UTF-8”。清除特殊字符检查代码中是否有从网页复制来的“智能引号”“ ”、长破折号—等将它们替换为普通ASCII字符,-。简化测试将出错的代码块内容减少到一行逐步添加定位到具体出错的字符。4.2 实现“像WebStorm一样”的精细语法高亮网络热词中提到了“设置cursor代码像webstorm代码一样高亮”这反映了用户对高亮精细度的追求。WebStorm等IDE能区分函数名、变量名、类名、参数等。listings默认做不到这么细但可以通过alsoletter、morekeywords结合emph强调样式来模拟。思路将不同语义的标识符定义为不同的“关键字列表”并分别设置样式。\lstdefinestyle{myJavaStyle}{ languageJava, % 第一类关键字语言保留字 keywords{class, public, static, void, int, return}, keywordstyle\color{purple}\bfseries, % 第二类关键字常用库类名视为“强调” emph{String, System, ArrayList, Integer}, emphstyle\color{blue}\bfseries, % 第三类用户自定义的类名或方法名另一种“强调” emph{[2]MyClass, calculateTotal, main}, emphstyle[2]\color{teal}, % 第四类常量 emph{[3]MAX_VALUE, PI, DEFAULT_NAME}, emphstyle[3]\color{orange!80!black}, commentstyle\color{gray}\itshape, stringstyle\color{red}, }在这个配置中keywords是语言本身的保留字。emph用于定义需要强调的标识符列表通过[2],[3]可以定义多组并分别用emphstyle[n]来指定样式。这样就能粗略地模拟IDE中不同颜色区分不同语义元素的效果。当然这需要你手动维护这些列表对于大型项目不现实但对于展示关键代码片段非常有效。4.3 插入代码片段与外部文件引用你不可能把所有代码都写在.tex文件里。管理大型项目代码时最佳实践是将代码保存在独立的文件中然后用\lstinputlisting引入。基本用法\lstinputlisting[languageC, caption{主程序入口}, labellst:main]{src/main.cpp}高级技巧只引用文件的一部分这是listings一个极其有用的功能可以只显示文件中的某几行或者排除某些行如冗长的版权声明。\lstinputlisting[ languagePython, caption{仅展示核心函数}, firstline20, % 从第20行开始 lastline35, % 到第35行结束 linerange{5-10, 30-40}, % 或者指定多个行范围 % firstnumber1, % 显示的行号从1开始而不是20 ]{src/long_script.py}在行内插入代码有时你只需要在句子里提到一个函数名或变量。可以使用\lstinline命令它类似于\verb但可以应用你定义的样式。在程序中请调用 \lstinline[languagePython]|my_function(arg1, arg2)| 来完成计算。|是分隔符你可以换成其他不冲突的字符比如!或。4.4 常见“坑”与解决方案汇总坑下划线_和百分号%导致编译错误。原因_在LaTeX中是下标命令%是注释符。当它们出现在代码字符串或注释中时会被LaTeX编译器误解。解决在lstset或样式定义中设置columnsfullflexible或使用literate参数转义更简单粗暴但有效的方法是设置texclfalse默认并启用mathescapefalse。对于%确保它不在listings认为是LaTeX代码的区域即texcltrue时需格外小心。坑代码边框或背景色溢出到页面外。原因当代码行过长超过文本宽度时listings默认不会换行breaklinesfalse导致内容溢出。解决务必设置breaklinestrue。对于更精细的控制可以设置breakatwhitespacetrue只在空格处断行和postbreak\mbox{\textcolor{red}{$\hookrightarrow$}\space}在折行处添加一个箭头指示符。坑行号与代码对不齐或者字体奇怪。原因行号的样式numberstyle可能和代码基本样式basicstyle不匹配比如字号、字族不同。解决确保numberstyle是basicstyle的子集或与之协调。例如basicstyle\ttfamily\small,numberstyle\tiny\ttfamily\color{gray}。使用相同的字族\ttfamily是关键。坑使用tcolorbox包装后代码高亮失效。原因tcolorbox的listing only选项可能没有正确传递listings的选项或者选项冲突。解决检查listing options{}里的设置是否完整特别是language和style必须在此指定。确保\lstset中的全局样式和你传递给tcolorbox的局部样式没有冲突。一个可靠的调试方法是先不用tcolorbox让listings单独工作正常再逐步添加tcolorbox包装。5. 综合案例构建一个可直接复用的LaTeX代码展示模板纸上得来终觉浅。最后我将分享一个我多年来在撰写技术报告和论文时使用的、高度可定制的完整模板。你可以直接复制到你的文档导言区并根据喜好调整颜色和参数。% 代码高亮与排版配置模板 % 保存为 listings_setup.tex在主文件中用 \input{listings_setup} 引入 \usepackage{xcolor} \usepackage{listings} \usepackage[most]{tcolorbox} \tcbuselibrary{listings, skins, breakable} % 1. 颜色定义 (Monokai主题风格) \definecolor{monokaiBG}{HTML}{272822} \definecolor{monokaiComment}{HTML}{75715E} \definecolor{monokaiGreen}{HTML}{A6E22E} \definecolor{monokaiCyan}{HTML}{66D9EF} \definecolor{monokaiPurple}{HTML}{AE81FF} \definecolor{monokaiOrange}{HTML}{FD971F} \definecolor{monokaiRed}{HTML}{F92672} \definecolor{monokaiYellow}{HTML}{E6DB74} % 2. 基础Listings样式 \lstdefinestyle{myBaseStyle}{ % 字体与排版 basicstyle\ttfamily\footnotesize\color{white}, backgroundcolor\color{monokaiBG}, % 换行与空格 breaklinestrue, breakatwhitespacetrue, postbreak\raisebox{0ex}[0ex][0ex]{\color{monokaiRed}\ensuremath{\hookrightarrow\space}}, keepspacestrue, tabsize4, showspacesfalse, showstringspacesfalse, % 行号 numbersleft, numberstyle\tiny\ttfamily\color{monokaiComment}, numbersep8pt, % 边框 framesingle, rulecolor\color{monokaiComment}, framerule0.8pt, % 编码 inputencodingutf8, extendedcharstrue, literate % 处理一些特殊字符 {á}{{\a}}1 {é}{{\e}}1 {í}{{\i}}1 {ó}{{\o}}1 {ú}{{\u}}1 {Á}{{\A}}1 {É}{{\E}}1 {Í}{{\I}}1 {Ó}{{\O}}1 {Ú}{{\U}}1 {à}{{\a}}1 {è}{{\e}}1 {ì}{{\i}}1 {ò}{{\o}}1 {ù}{{\u}}1 {À}{{\A}}1 {È}{{\E}}1 {Ì}{{\I}}1 {Ò}{{\O}}1 {Ù}{{\U}}1 {ä}{{\a}}1 {ë}{{\e}}1 {ï}{{\i}}1 {ö}{{\o}}1 {ü}{{\u}}1 {Ä}{{\A}}1 {Ë}{{\E}}1 {Ï}{{\I}}1 {Ö}{{\O}}1 {Ü}{{\U}}1 {â}{{\^a}}1 {ê}{{\^e}}1 {î}{{\^i}}1 {ô}{{\^o}}1 {û}{{\^u}}1 {Â}{{\^A}}1 {Ê}{{\^E}}1 {Î}{{\^I}}1 {Ô}{{\^O}}1 {Û}{{\^U}}1 {œ}{{\oe}}1 {Œ}{{\OE}}1 {æ}{{\ae}}1 {Æ}{{\AE}}1 {ß}{{\ss}}1 {ç}{{\c c}}1 {Ç}{{\c C}}1 {ø}{{\o}}1 {å}{{\r a}}1 {Å}{{\r A}}1 {€}{{\euro}}1 {£}{{\pounds}}1 {«}{{\guillemotleft}}1 {»}{{\guillemotright}}1 {ñ}{{\~n}}1 {Ñ}{{\~N}}1 {¿}{{?}}1 {…}{{\ldots}}1 {≥}{{}}1 {≤}{{}}1 {≠}{{!}}1 {…}{{\ldots}}1 {→}{{-}}1 {←}{{-}}1 {∞}{{\infty}}1 {✓}{{\checkmark}}1 {✗}{{\times}}1 } % 3. 各语言特定样式 (继承基础样式) \lstdefinestyle{Python}{ stylemyBaseStyle, languagePython, keywordstyle\color{monokaiPurple}\bfseries, commentstyle\color{monokaiComment}\itshape, stringstyle\color{monokaiYellow}, emph{self, True, False, None, __init__, __name__}, % 内置常量/特殊方法 emphstyle\color{monokaiGreen}, morekeywords{with, as, assert, yield, async, await}, % Python3 关键字 } \lstdefinestyle{JavaScript}{ stylemyBaseStyle, languageJavaScript, keywordstyle\color{monokaiPurple}\bfseries, commentstyle\color{monokaiComment}\itshape, stringstyle\color{monokaiYellow}, emph{console, document, window, alert, JSON, Math}, % 常用对象 emphstyle\color{monokaiCyan}, } \lstdefinestyle{Bash}{ stylemyBaseStyle, languagebash, keywordstyle\color{monokaiGreen}, % 命令用绿色 commentstyle\color{monokaiComment}\itshape, stringstyle\color{monokaiYellow}, morekeywords{sudo, apt, git, curl, wget, echo, ls, cd}, % 常见命令 alsoletter{-}, % 将-视为关键字的一部分以便高亮ls -la } % 4. 使用tcolorbox创建漂亮的代码框 \newtcblisting{codeblock}[2][]{ % #1: 可选标题 #2: 语言/样式 listing only, listing options{style#2}, % 应用上面定义的语言样式 colbackmonokaiBG, colframemonokaiComment, arc4pt, boxrule1pt, title{\sffamily\small 代码 \thetcbcounter\ifthenelse{\equal{#1}{}}{}{: #1}}, fonttitle\bfseries\sffamily, breakable, enhanced, attach title to upper, before skip12pt, after skip12pt, drop fuzzy shadowmonokaiBG!50!black, } % 5. 便捷命令 % 行内代码 \newcommand{\inlinecode}[2][]{\lstinline[stylemyBaseStyle, #1]|#2|} % 引入外部文件带框 \newcommand{\inputcode}[3][]{\begin{codeblock}[#1]{#2}\lstinputlisting[style#2]{#3}\end{codeblock}} % 设置全局默认 \lstset{stylemyBaseStyle} % 设置一个安全的全局默认 \renewcommand{\lstlistingname}{代码} \renewcommand{\lstlistlistingname}{代码清单}使用示例% 在主文件中 \input{listings_setup} % 引入配置 \begin{document} 这是一个行内代码示例\inlinecode[languagePython]{print(Hello)}。 % 使用自定义环境插入Python代码 \begin{codeblock}[快速排序算法]{Python} def quicksort(arr): if len(arr) 1: return arr pivot arr[len(arr) // 2] left [x for x in arr if x pivot] middle [x for x in arr if x pivot] right [x for x in arr if x pivot] return quicksort(left) middle quicksort(right) \end{codeblock} % 引入外部JS文件 \inputcode[配置文件示例]{JavaScript}{config/settings.js} % 生成代码目录 \lstlistoflistings \end{document}这个模板提供了从颜色主题、基础样式、多语言支持到精美包装的一站式解决方案。你唯一需要做的可能就是根据你的文档主题色微调一下\definecolor那部分。它解决了编码、换行、特殊字符、浮动引用等绝大多数常见问题让你能专注于内容本身而不是排版调试。