用 Python 自动化把 JavaScript 代码转换为 Word 文档

将 JavaScript 源码整理为可交付的 Word 文档，在代码审计报告、技术文档归档、教学材料准备等场景中并不少见。手动复制粘贴代码并逐段调整格式效率很低，且难以保证多次产出的一致性。本文讨论一种以脚本驱动的转换思路，并分析其中的技术取舍与边界。

问题拆解

把 JavaScript 代码放进 Word，难点不在"写入"，而在"保真"。Word 本身不具备解析代码语法的能力，纯文本粘贴会丢失缩进、换行与着色标记；即便手动设置等宽字体，嵌套结构、字符串与注释的视觉区分仍然依赖人工判断。因此，一个可自动化的路径需要把"语法理解"和"文档承载"两件事分开处理。

一种常见做法是引入中间层：先把源码渲染为带内联样式的 HTML，再交由文档库导入。Pygments 负责前者------它按词法规则把代码切分为 token 并着色；Spire.Doc for Python 负责后者------它在不依赖 Microsoft Word 环境的前提下构建 .docx 并解析 HTML 片段。两者组合后，整个流程可在 Python 脚本内闭环完成。

依赖安装：

bash 复制代码

pip install spire.doc
pip install pygments

实现与关键参数

下面的函数完成单文件转换。读取源码后，JavascriptLexer 做词法分析，HtmlFormatter 生成 HTML。其中 noclasses=True 是决定成败的参数：它把样式以内联方式写入标签，而不是输出 class 并由外部样式表定义。文档库在导入 HTML 时通常不加载外部 CSS，若省略该参数，着色信息会在导入阶段丢失。

python 复制代码

from spire.doc import *
from pygments import highlight
from pygments.lexers import JavascriptLexer
from pygments.formatters import HtmlFormatter

def convert_js_to_word(input_file: str, output_file: str) -> None:
    """将 JavaScript 文件转换为带有语法高亮的 Word 文档。"""

    with open(input_file, "r", encoding="utf-8") as file:
        js_code = file.read()

    document = Document()
    section = document.AddSection()
    section.PageSetup.Margins.All = 50

    title_paragraph = section.AddParagraph()
    title_text = title_paragraph.AppendText(f"源代码：{input_file}")
    title_text.CharacterFormat.FontName = "微软雅黑"
    title_text.CharacterFormat.FontSize = 14
    title_text.CharacterFormat.Bold = True
    title_paragraph.Format.AfterSpacing = 10

    html_formatter = HtmlFormatter(
        nowrap=True,
        style='colorful',
        noclasses=True
    )

    highlighted_html = highlight(js_code, JavascriptLexer(), html_formatter)

    code_paragraph = section.AddParagraph()
    code_paragraph.AppendHTML(
        f'<pre style="font-family: Consolas; font-size: 10pt;">{highlighted_html}</pre>'
    )

    document.SaveToFile(output_file, FileFormat.Docx)
    document.Close()

    print(f"已将 {input_file} 转换为 {output_file}")

convert_js_to_word("app.js", "JavaScriptCode.docx")

几个参数的取舍值得说明。外层 <pre> 标签不可省略，否则 HTML 中的连续空白与换行在 Word 渲染时会被合并，代码缩进随之塌陷。等宽字体选 Consolas 是为了让对齐在 Word 中保持稳定；style 可换成 monokai、vim、vs 等内置配色，属于阅读偏好问题而非功能差异。Margins.All = 50 收窄页边距，为长代码行争取横向空间，这是排版层面的实用调整。

词法器选择的边界

上述实现针对普通 JavaScript。若源文件是 React 的 JSX，JavascriptLexer 对组件标签与 {} 内表达式的切分不够准确，着色会出现错位。换用 JsxLexer 即可改善，其余流程不变：

python 复制代码

from pygments.lexers import JsxLexer

highlighted_html = highlight(jsx_code, JsxLexer(), html_formatter)

这提示了一个更一般的问题：词法器的选择直接决定输出质量，而 Pygments 的覆盖范围虽广，对某些方言（如 TypeScript 的装饰器、较新的语法提案）仍可能存在识别滞后。转换前确认词法器与源码方言匹配，比事后修补格式更省力。

批量场景下的工程约束

单文件跑通之后，批量处理是自然的下一步：遍历目录、按扩展名筛选、逐个调用转换函数。这里有两个容易被忽略的约束。其一是资源释放------循环中每次都应调用 document.Close()，否则文档对象累积会推高内存占用。其二是编码------非 UTF-8 源文件需显式指定 encoding，带 BOM 的文件用 utf-8-sig 读取，否则中文注释可能乱码。

超大文件（例如上万行）会暴露另一层限制：一次性渲染 HTML 并导入，生成过程明显变慢。分块处理是一种折中，但分块会切断跨行的语法结构------多行字符串、块注释、模板字面量都可能在切分点被破坏。因此分块是否可行，取决于源码中这类结构的密度，而非单纯的行数。

适用性与局限

这套"代码→HTML→Word"管道的价值在于可复现与可批量化：转换逻辑全部由脚本控制，能嵌入构建流程，源码更新后重跑即得同步文档。但它的能力上限由 Word 对 HTML/CSS 的支持范围决定。复杂的代码布局------侧边标注、折叠区域、跨页断行控制------无法通过这条路径还原；精细排版仍需在 Word 内二次加工，或改用 LaTeX、Pandoc 等以排版为核心的方案。

换言之，该方法适合"结构清晰、以内容归档为目的"的场景，不适合"以版式设计为核心"的交付物。明确这一边界，比追求全自动更有实际意义。