解决Python处理Word文档时的中文乱码与编码错误

一、快速定位：三类典型的中文乱码与报错表现

处理 Word 文档遇到问题时，首先需要依据具体的报错提示与视觉呈现，准确定位问题发生的层面：

• 控制台终止型报错：运行脚本直接弹出 UnicodeDecodeError: 'utf-8' codec can't decode byte ... in position ... 或 UnicodeEncodeError: 'gbk' codec can't encode character ...。这类错误发生于数据读取与输出阶段，属于字符字节流解码失败。
• 视觉显示回退型乱码：Python 脚本正常执行完成并生成了 .docx，但在 Microsoft Word 或 WPS 中打开后，中文内容变成了方块（“豆腐块”）、问号，或者设置的中文字体（如微软雅黑、黑体）无效，全部变回了宋体甚至英文字体。这属于样式层面的字体族映射缺失，文本字符本身并未损坏。
• 外部数据混合型乱码：从数据库、旧系统导出的 CSV 或抓取的网页文本写入 Word 时，文档中直接显示“锟斤拷”、“烫烫烫”等乱码字符。这表明数据在进入 Word 处理流程前就已发生了编码解析错误。

二、核心痛点：python-docx 处理 .docx 时的东亚字体映射缺失

很多开发者使用 python-docx 库生成或修改文档时，明明写下了类似 run.font.name = '微软雅黑' 的代码，但在 Word 中打开文档时，中文依然以“宋体”或生硬的默认字体显示。如果不深入了解 OpenXML 标准，极易将其误认为是 Python 编码错误。

.docx 文件实质上是一个由 ZIP 格式压缩的多 XML 文件集合。在底层 WordprocessingML 规范中，文字被存放在 w:r（Run）节点的 w:t 标签内，默认采用标准 UTF-8 编码，因此文本内容本身不会丢失。字体设置由 w:rPr（Run 属性）中的 w:rFonts 节点决定：

<!-- 仅调用 run.font.name = '微软雅黑' 时生成的底层 XML -->
<w:rPr>
    <w:rFonts w:ascii="微软雅黑" w:hAnsi="微软雅黑"/>
</w:rPr>

从上述 XML 片段可见，run.font.name 仅将字体赋给了 w:ascii（ASCII 字符）和 w:hAnsi（高位 ANSI 字符）。当 Word 渲染引擎读取到中文字符（Unicode 范围属于东亚象形文字）时，发现没有声明 w:eastAsia（东亚字体），便会直接放弃该设置，自动回退到 Office 软件预设的默认中文字体（通常为宋体或系统缺省字体），引发视觉上的样式错乱。

规范解决方案：完整双轨字体绑定代码

要让 python-docx 生成的中文字体生效，必须借助其底层的 docx.oxml.ns.qn 工具，显式向 XML 节点注入 w:eastAsia 命名空间属性。以下是生产环境推荐的标准函数封装：

import docx
from docx.shared import Pt, RGBColor
from docx.oxml.ns import qn

def set_chinese_font(run, font_name='微软雅黑', font_size_pt=11, color_rgb=(44, 53, 61)):
    """
    为 python-docx 的 Run 对象正确应用中西文字体
    :param run: docx.text.run.Run 实例
    :param font_name: 中文字体名称，如 '微软雅黑'、'黑体'、'宋体'
    :param font_size_pt: 字号大小（磅）
    :param color_rgb: 字体颜色元组 (R, G, B)
    """
    # 1. 设置西文字符字体
    run.font.name = font_name
    
    # 2. 关键：向底层 XML 注入东亚字体映射
    run._element.rPr.rFonts.set(qn('w:eastAsia'), font_name)
    
    # 3. 设置字号与颜色
    if font_size_pt:
      run.font.size = Pt(font_size_pt)
    if color_rgb:
      run.font.color.rgb = RGBColor(*color_rgb)

# 示例：创建文档并写入中文
doc = docx.Document()
p = doc.add_paragraph()
run = p.add_run("这是一段规范渲染的中文技术内容。English text 123.")
set_chinese_font(run, font_name='微软雅黑', font_size_pt=12)

doc.save("output_chinese_sample.docx")

style = doc.styles['Normal']
style.font.name = '微软雅黑'
style.element.rPr.rFonts.set(qn('w:eastAsia'), '微软雅黑')

三、源头阻断：旧版 .doc 二进制文件与外部 I/O 编码冲突

除 .docx 样式问题外，另一类高频故障是处理 .doc 文件时发生的硬性崩溃。许多早期遗留系统产生的是二进制 .doc 文件，新手常尝试使用常规的 Python 文本流进行操作：

# 典型错误示例：直接试图用 open 读取 Word 二进制文档
with open("legacy_report.doc", "r", encoding="utf-8") as f:
    content = f.read()  # 直接触发 UnicodeDecodeError

.doc 并不是像 .txt 或 .csv 那样的纯文本文件，而是微软基于 OLE2（Object Linking and Embedding）复合文档规范构建的复杂二进制结构（CFBF 格式）。文件头包含了魔数、分区块映射表和压缩流，其中混杂了非文本控制字节，直接按 UTF-8、GBK 等字符集解码必定报错。

1. 将旧版 .doc 转换为 .docx

处理 .doc 时，应在预处理阶段将其转换为基于 OpenXML 的 .docx，再交由 python-docx 处理。在 Windows 环境下，可使用 pywin32 完成自动化转换：

import os
import win32com.client

def convert_doc_to_docx(doc_path):
    """
    将旧版 .doc 转换为 .docx 格式
    注意：doc_path 必须为包含驱动器号的绝对路径
    """
    abs_doc_path = os.path.abspath(doc_path)
    abs_docx_path = abs_doc_path + "x"
    
    # 实例化 Word 应用程序对象
    word_app = win32com.client.DispatchEx("Word.Application")
    word_app.Visible = False
    
    try:
      doc = word_app.Documents.Open(abs_doc_path)
      # 16 代表 wdFormatXMLDocument 即 docx 格式
      doc.SaveAs2(abs_docx_path, FileFormat=16)
      doc.Close()
      return abs_docx_path
    finally:
      word_app.Quit()

2. 外部中文数据写入与读取时的编码统一

当从外部数据文件（例如用户上传的日志、爬虫抓取的数据）读取文字并写入 Word 文档时，必须在读取阶段明确数据源的实际编码：

• 对于常规现代文本，统一以 open(file_path, 'r', encoding='utf-8') 读取。
• 对于旧版 Windows 软件导出的文本（如 GBK、GB2312、CP936），应显式指定 encoding='gbk'。解码进入 Python 内存后均统一为原生 str（Unicode 抽象），后续写入 python-docx 便不会出现异常。
• 针对带有 BOM（Byte Order Mark）的 UTF-8 文本，应使用 encoding='utf-8-sig'，防止隐式字节头 \ufeff 成为段落首字符导致排版异常。

四、环境与边界：控制台环境、中文路径与兜底容错机制

1. Windows 控制台打印报错：UnicodeEncodeError

当 Python 成功解析出 Word 中的中文字符后，使用 print(text) 尝试在终端输出时却突然报错：

UnicodeEncodeError: 'gbk' codec can't encode character '\u2022' in position ...

这是因为旧版 Windows 命令行控制台默认代码页为 936（GBK），而 Word 文档中常包含项目符号（如 •）、特殊破折号或生僻字，这些字符超出 GBK 字符集范围，控制台在编码时抛出异常。解决方法是在程序启动入口处配置标准流编码重定向：

import sys

# Python 3.7+ 推荐写法：重新配置标准输出编码为 utf-8，并采用替换容错策略
if sys.platform == "win32":
    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
    sys.stderr.reconfigure(encoding='utf-8', errors='replace')

2. 中文路径与特殊字符的文件名处理

在 Windows 环境下，若 Word 文档文件名或所在文件夹路径包含中文，偶发会出现 FileNotFoundError。编写自动化脚本时应遵循以下规范：

• 全部使用 os.path.abspath() 或 pathlib.Path 展开为绝对路径，避免在多模块调用时相对路径混淆。
• 不要对路径字符串做多余的手动 encode('gbk') 或 encode('utf-8') 转换，直接传递原生的 Unicode 字符串给 docx.Document(path) 即可，Python 3 底层会调用 Windows 原生 Unicode API（如 CreateFileW）。

五、全流程防乱码总结与操作核对表

为了在工程开发中彻底避免中文乱码与编码故障，建议在代码编写与上线前对照以下四项核心规范逐项核验：