Python代码高亮神器：Pygments从入门到实战，轻松实现代码语法高亮

一、Pygments库基础介绍

Pygments是Python生态中通用、强大的语法高亮库，支持数百种编程语言、配置文件与标记语言，核心原理是通过词法分析拆分代码为不同语法单元，再匹配格式化规则生成高亮文本。它可输出HTML、RTF、图片、ANSI等多种格式，采用BSD许可证开源，轻量无依赖、集成简单，缺点是不具备代码编辑与运行能力，仅专注代码高亮与格式化。

二、Pygments安装方法

Pygments对Python版本兼容性极强，支持Python 3.6及以上版本，安装过程非常简洁，只需要使用Python官方的包管理工具pip即可完成，打开电脑的命令行工具（Windows使用CMD或PowerShell，macOS与Linux使用终端），直接执行以下安装命令：

pip install pygments

等待命令执行完成，没有报错信息就代表安装成功。为了验证是否正确安装，可以在命令行中输入以下命令查看Pygments的版本号：

pygmentize -V

如果能够正常显示版本号，说明Pygments已经成功安装到你的Python环境中，可以直接在项目中导入使用，也可以直接在命令行使用它提供的命令行工具。

Pygments同时提供了两种使用方式，一种是命令行工具pygmentize，可以直接对文件进行高亮处理，不需要编写Python代码，适合快速使用；另一种是Python API调用，可以在自己的Python项目、Web框架、桌面软件中灵活集成，满足定制化开发需求，两种方式都简单易懂，小白也能快速掌握。

三、Pygments命令行快速使用

对于不想编写代码，只想快速给代码文件做高亮处理的用户来说，命令行工具是最佳选择，它操作简单，执行一条命令就能生成高亮结果，支持直接输出带颜色的终端内容，也能生成网页格式的代码片段。

3.1 命令行基础语法

Pygments命令行工具的基础使用语法如下：

pygmentize [参数] 代码文件

常用参数介绍：

• -o：指定输出文件路径
• -f：指定输出格式，如html、terminal、rtf等
• -l：指定代码语言，不指定时会自动识别
• -O：设置输出选项，比如指定高亮主题、是否显示行号
• -S：列出所有支持的高亮主题

3.2 命令行实用示例

1. 直接在终端高亮显示Python代码
   新建一个Python文件，命名为test.py，写入以下测试代码：

def add(a, b):
    return a + b

if __name__ == "__main__":
    result = add(10, 20)
    print(f"计算结果: {result}")

然后在命令行执行：

pygmentize test.py

执行后终端会直接输出带有语法高亮的代码，关键字、函数名、字符串都会显示不同颜色，清晰易读。

2. 生成HTML格式的高亮代码
   如果需要把高亮代码放到网页上展示，可以执行以下命令生成HTML文件：

pygmentize -f html -o test.html test.py

执行完成后，会在当前目录生成test.html文件，打开后就能看到语法高亮的代码片段，自带样式，无需手动编写CSS。

3. 带行号与指定主题的HTML输出
   想要代码更规范，添加行号并更换高亮主题，可以使用以下命令：

pygmentize -f html -O linenos=1,style=monokai -o test_lineno.html test.py

这个命令会生成带有行号、使用monokai深色主题的HTML代码，适合技术博客、文档展示。

4. 查看所有支持的高亮主题
   Pygments自带数十种高亮主题，满足不同使用场景，执行以下命令可以查看全部主题：

pygmentize -L styles

常用主题有monokai、vs、xcode、github、friendly等，可以根据喜好自由切换。

命令行方式适合临时使用，而在实际开发中，我们更多会在Python代码中调用Pygments的API，实现灵活的定制化高亮功能，这也是Pygments最核心的使用方式。

四、Python代码中使用Pygments API

在Python项目中使用Pygments，主要依靠四个核心组件：词法分析器(Lexer)、格式化器(Formatter)、样式(Style)、高亮函数(highlight)，它们分工明确，配合使用就能完成各种代码高亮需求。

4.1 核心组件说明

• Lexer：词法分析器，负责把代码拆分成不同的语法单元，如关键字、变量、字符串、注释等，Pygments支持数百种语言，每种语言对应专属的Lexer
• Formatter：格式化器，负责把拆分后的语法单元渲染成目标格式，如HTML、终端颜色、RTF等
• Style：样式类，定义不同语法单元的颜色、字体等样式，对应命令行中的主题
• highlight：核心高亮函数，接收代码、Lexer、Formatter，直接输出高亮结果

4.2 基础API使用示例

最简单的使用方式，就是直接导入highlight函数，指定语言和输出格式，以下是完整示例：

# 导入Pygments核心模块
from pygments import highlight
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter

# 待高亮的Python代码
code = """
def hello_world():
    # 这是一个注释
    print("Hello, Pygments!")
    for i in range(5):
        print(i)

hello_world()
"""

# 创建Python词法分析器和HTML格式化器
lexer = PythonLexer()
formatter = HtmlFormatter()

# 执行高亮处理
result = highlight(code, lexer, formatter)

# 输出结果并保存到HTML文件
with open("pygments_demo.html", "w", encoding="utf-8") as f:
    f.write(result)

print("HTML文件生成成功！")

代码说明：

1. 首先导入Pygments的核心模块，PythonLexer是专门用于Python代码的词法分析器，HtmlFormatter用于生成HTML格式结果
2. 定义一段需要高亮的Python代码，包含函数、注释、循环、打印语句
3. 实例化词法分析器和格式化器，调用highlight函数完成高亮
4. 将生成的HTML代码写入文件，打开文件就能看到美观的语法高亮效果

这个示例是Pygments最基础的用法，只需要几行代码就能实现完整的代码高亮功能，对新手非常友好。

4.3 自定义样式与行号

在实际使用中，我们通常需要添加行号、更换高亮主题、调整代码样式，Pygments提供了丰富的配置参数，以下是定制化示例：

from pygments import highlight
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter

# 待高亮代码
code = """
import numpy as np

# 计算数组平均值
arr = np.array([1, 2, 3, 4, 5])
avg = np.mean(arr)
print(f"数组平均值: {avg}")
"""

# 配置格式化器：显示行号、使用monokai主题、代码带边框
formatter = HtmlFormatter(
    linenos=True,          # 显示行号
    style="monokai",       # 指定高亮主题
    full=True,             # 生成完整HTML页面，而非仅代码片段
    title="Pygments高亮示例", # HTML页面标题
    cssclass="code-block"  # 自定义CSS类名
)

# 生成高亮HTML
result = highlight(code, PythonLexer(), formatter)

with open("custom_style.html", "w", encoding="utf-8") as f:
    f.write(result)

代码说明：

1. linenos=True 开启行号显示，方便代码定位
2. style="monokai" 使用经典的monokai深色主题，护眼且美观
3. full=True 生成完整的HTML文件，包含DOCTYPE、head、body标签，可直接用浏览器打开
4. cssclass 可以自定义代码块的CSS类名，方便后续在网页中统一调整样式

运行代码后生成的HTML文件，是一个完整可独立运行的页面，代码高亮、行号、样式全部齐全，直接用于网页展示非常合适。

4.4 终端输出高亮代码

除了生成HTML，Pygments还支持在Python程序中直接输出带颜色的终端代码，适合命令行工具、脚本开发，示例如下：

from pygments import highlight
from pygments.lexers import get_lexer_by_name
from pygments.formatters import TerminalFormatter

# 支持多种语言高亮，这里以JSON为例
json_code = '''
{
    "name": "Pygments",
    "function": "代码高亮",
    "language": ["Python", "Java", "C++", "JavaScript"],
    "version": "2.16.1"
}
'''

# 指定JSON语言词法分析器，终端格式化器
lexer = get_lexer_by_name("json")
formatter = TerminalFormatter()

# 输出高亮结果
print("JSON代码高亮效果：")
highlight(json_code, lexer, formatter)

代码说明：

1. get_lexer_by_name 可以通过语言名称获取对应的词法分析器，不用单独导入
2. TerminalFormatter 用于生成终端支持的颜色代码，直接打印就能显示彩色高亮
3. 支持JSON、Java、C++、JavaScript等绝大多数常用语言，通用性极强

运行这段代码，终端会直接输出彩色的JSON代码，关键字、字符串、数字颜色区分明显，大幅提升命令行工具的可读性。

4.5 自动识别代码语言

Pygments支持自动识别代码语言，不需要手动指定，适合处理未知语言的代码，示例如下：

from pygments import highlight
from pygments.lexers import guess_lexer
from pygments.formatters import HtmlFormatter

# 一段JavaScript代码，不指定语言
code = """
function sayHi(name) {
    return "Hello, " + name;
}
console.log(sayHi("Pygments"));
"""

# 自动识别代码语言
lexer = guess_lexer(code)
print(f"自动识别的语言: {lexer.name}")

# 生成高亮结果
result = highlight(code, lexer, HtmlFormatter(full=True, style="github"))

with open("auto_detect.html", "w", encoding="utf-8") as f:
    f.write(result)

代码说明：

1. guess_lexer 函数会根据代码内容自动判断编程语言，准确率极高
2. 示例中代码为JavaScript，程序会自动识别并使用对应的词法分析器
3. 这种方式适合爬虫、代码仓库工具等无法预知语言的开发场景

自动识别功能大幅降低了使用成本，新手不用记忆各种语言的名称，直接交给Pygments处理即可。

五、Pygments实际开发案例

Pygments在实际项目中应用非常广泛，比如技术博客、在线编辑器、文档生成工具、代码审查系统等，下面以Django Web项目中集成代码高亮和Python批量生成代码文档两个实战案例，演示Pygments的真实使用场景。

5.1 案例一：批量生成带高亮的代码文档

很多开发者需要整理学习笔记、代码文档，手动给代码加高亮非常麻烦，使用Pygments可以编写一个批量处理脚本，自动读取代码文件，生成HTML格式的高亮文档，完整代码如下：

import os
from pygments import highlight
from pygments.lexers import get_lexer_for_filename
from pygments.formatters import HtmlFormatter

def batch_code_highlighter(input_dir, output_dir):
    """
    批量高亮代码文件并生成HTML文档
    :param input_dir: 代码文件所在目录
    :param output_dir: 输出HTML目录
    """
    # 创建输出目录
    if not os.path.exists(output_dir):
        os.makedirs(output_dir)

    # 遍历目录下所有代码文件
    for filename in os.listdir(input_dir):
        file_path = os.path.join(input_dir, filename)

        # 只处理文件，跳过子目录
        if os.path.isfile(file_path):
            try:
                # 根据文件后缀自动获取词法分析器
                lexer = get_lexer_for_filename(file_path)

                # 配置格式化器
                formatter = HtmlFormatter(
                    linenos=True,
                    style="vs",
                    full=True,
                    title=f"代码高亮 - {filename}"
                )

                # 读取代码内容
                with open(file_path, "r", encoding="utf-8") as f:
                    code_content = f.read()

                # 生成高亮HTML
                html_content = highlight(code_content, lexer, formatter)

                # 保存HTML文件
                output_filename = os.path.splitext(filename)[0] + ".html"
                output_path = os.path.join(output_dir, output_filename)

                with open(output_path, "w", encoding="utf-8") as f:
                    f.write(html_content)

                print(f"处理成功: {filename} -> {output_filename}")

            except Exception as e:
                print(f"处理失败: {filename}，错误信息: {str(e)}")

# 执行批量处理
if __name__ == "__main__":
    # 代码文件目录
    INPUT_FOLDER = "my_codes"
    # 输出HTML目录
    OUTPUT_FOLDER = "html_docs"

    batch_code_highlighter(INPUT_FOLDER, OUTPUT_FOLDER)

案例说明：

1. 这个脚本可以批量处理指定目录下的所有代码文件，支持Python、Java、JavaScript、C、C++等任意Pygments支持的语言
2. 根据文件后缀自动识别语言，自动添加行号和高亮样式
3. 生成独立的HTML文档，可直接用浏览器打开查看，适合整理学习资料、项目代码文档
4. 代码结构清晰，添加了异常处理，运行稳定，小白也能直接使用

使用时只需要在脚本同目录创建my_codes文件夹，放入代码文件，运行脚本即可在html_docs文件夹得到高亮后的HTML文件。

5.2 案例二：在Flask Web项目中实现代码高亮

在Web开发中，经常需要在网页上展示代码片段，Pygments可以轻松集成到Flask、Django等Web框架中，以下是Flask简易示例：

from flask import Flask, render_template_string
from pygments import highlight
from pygments.lexers import PythonLexer
from pygments.formatters import HtmlFormatter

app = Flask(__name__)

@app.route("/")
def show_code():
    # 要展示的代码
    code = """
    from flask import Flask
    app = Flask(__name__)

    @app.route("/")
    def index():
        return "Hello Flask!"

    if __name__ == "__main__":
        app.run(debug=True)
    """

    # 生成高亮代码和CSS样式
    formatter = HtmlFormatter(linenos=True, style="monokai")
    highlighted_code = highlight(code, PythonLexer(), formatter)
    css_style = formatter.get_style_defs(".code-highlight")

    # HTML模板
    html_template = """
    <!DOCTYPE html>
    <html>
    <head>
        <meta charset="utf-8">
        <title>Flask+Pygments代码高亮</title>
        <style>{{ css_style }}</style>
    </head>
    <body>
        <h2>Flask示例代码</h2>
        <div class="code-highlight">
            {{ highlighted_code|safe }}
        </div>
    </body>
    </html>
    """

    return render_template_string(html_template, 
                                highlighted_code=highlighted_code,
                                css_style=css_style)

if __name__ == "__main__":
    app.run(debug=True)

案例说明：

1. 集成Pygments到Flask项目，只需要几行代码就能实现网页代码高亮
2. formatter.get_style_defs 可以自动生成对应的CSS样式，直接嵌入网页即可
3. 代码支持行号、自定义主题，与网页完美融合，适合开发技术博客、在线教程网站
4. 代码结构简单，易于扩展，可适配任意Python Web框架

运行这个Flask程序，访问浏览器就能看到带有精美高亮的Flask代码，效果和专业技术网站一致。

六、相关资源

• Pypi地址：https://pypi.org/project/Pygments
• Github地址：https://github.com/pygments/pygments
• 官方文档地址：https://pygments.org/docs/

关注我，每天分享一个实用的Python自动化工具。