Claude Code 处理 Word 文件的完整指南 - 学习笔记-Claude Code-上海佼艾

一、Claude Code 处理 Word 文件的能力边界

Claude Code 是一个 AI 编程助手，本身并不直接操作二进制文件格式。要处理 Word 文档（.docx），需要理解它的能力边界和正确的协作方式。

核心认知：Claude Code 无法直接打开或编辑 .docx 文件，但可以通过生成和运行 Python 代码来间接操作 Word 文档。正确的工作流是：由 Claude Code 编写 Python 脚本，脚本利用 python-docx 等库完成实际的文档操作。

能力边界表

操作类型	Claude Code 能否直接完成	推荐方案
读取 .docx 文本内容	不能（二进制格式）	用 python-docx 提取文本后读取
创建新的 Word 文档	不能	用 python-docx 生成 .docx 文件
修改现有 Word 文档	不能	用 python-docx 库编辑
查看文档结构（段落、表格）	不能直接	提取为 Markdown 或 JSON 后再分析
分析文档内容语义	可以（提取文本后）	先提取纯文本，再交给 Claude Code 分析
批量处理多个文档	可以（通过编写脚本）	Claude Code 编写循环脚本批量处理

提示

在向 Claude Code 发起 Word 处理任务时，只需描述你想要的最终结果，Claude Code 会自动生成对应的 Python 代码（基于 python-docx）来完成操作。你不需要精通 python-docx API，Claude Code 会帮你处理技术细节。

二、使用 python-docx 库读取和编辑 Word 文档

python-docx 是目前最成熟的 Python 操作 Word 文档的库，它支持 .docx 格式（Office Open XML）的读写。以下从环境搭建到实战操作进行全面介绍。

2.1 环境准备

# 安装 python-docx
pip install python-docx

2.2 读取 Word 文档的基础操作

from docx import Document

# 打开文档
doc = Document('example.docx')

# 读取所有段落文本
for i, para in enumerate(doc.paragraphs):
    if para.text.strip():
        print(f"段落 {i}: {para.text}")

# 读取文档中的所有表格
for table_idx, table in enumerate(doc.tables):
    print(f"--- 表格 {table_idx + 1} ---")
    for row in table.rows:
        cells = [cell.text for cell in row.cells]
        print(" | ".join(cells))

工作原理：.docx 文件本质是一个 ZIP 压缩包，内部包含 XML 文件。python-docx 库负责解压、解析 XML、提供 Pythonic 的 API，修改后再重新打包为 .docx。这种架构使得我们可以在不安装 Microsoft Office 的情况下操作 Word 文档。

2.3 创建和编辑 Word 文档

from docx import Document
from docx.shared import Pt, Inches, Cm, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH

# 创建新文档
doc = Document()

# 添加标题
doc.add_heading('我的文档标题', level=0)

# 添加段落并设置格式
para = doc.add_paragraph('这是一段正文内容。')
para.alignment = WD_ALIGN_PARAGRAPH.JUSTIFY
run = para.add_run('这是加粗的红色文字')
run.bold = True
run.font.color.rgb = RGBColor(0xFF, 0x00, 0x00)
run.font.size = Pt(14)

# 添加表格
table = doc.add_table(rows=3, cols=4)
table.style = 'Light Grid Accent 1'
for i, row in enumerate(table.rows):
    for j, cell in enumerate(row.cells):
        cell.text = f"行{i+1} 列{j+1}"

# 保存
doc.save('output.docx')

实践经验

Claude Code 最擅长的是帮你写出上述这类样板代码。你只需用自然语言描述"创建一个包含标题、三段正文和一个3行4列表格的文档"，Claude Code 就会自动生成对应的 python-docx 代码。这能极大地提高文档自动化处理的效率。

三、Word 文档内容提取：文本、表格、图片、样式

从 Word 文档中提取结构化信息是文档处理中最常见的需求。下面分别讨论不同类型内容的提取方法。

3.1 文本内容提取

def extract_all_text(filepath):
    doc = Document(filepath)
    full_text = []
    # 提取段落文本
    for para in doc.paragraphs:
        full_text.append(para.text)
    # 提取表格文本
    for table in doc.tables:
        for row in table.rows:
            row_text = [cell.text for cell in row.cells]
            full_text.append(" | ".join(row_text))
    return "\n".join(full_text)

text = extract_all_text('report.docx')
print(text[:500])  # 预览前500字符

3.2 图片提取

from docx.opc.constants import RELATIONSHIP_TYPE as RT
import os

def extract_images(docx_path, output_dir):
    doc = Document(docx_path)
    img_count = 0
    for rel in doc.part.rels.values():
        if "image" in rel.reltype:
            img = rel.target_part
            ext = os.path.splitext(img.partname)[1]
            filename = f"image_{img_count}{ext}"
            with open(os.path.join(output_dir, filename), 'wb') as f:
                f.write(img.blob)
            img_count += 1
    return img_count

count = extract_images('document.docx', './images/')
print(f"成功提取 {count} 张图片")

3.3 样式信息提取

def extract_styles(filepath):
    doc = Document(filepath)
    styles_info = []
    for i, para in enumerate(doc.paragraphs):
        if para.text.strip():
            info = {
                'index': i,
                'text': para.text[:50],
                'style': para.style.name,
                'alignment': str(para.alignment),
                'runs': []
            }
            for run in para.runs:
                info['runs'].append({
                    'bold': run.bold,
                    'italic': run.italic,
                    'font_size': str(run.font.size),
                    'font_name': run.font.name
                })
            styles_info.append(info)
    return styles_info

提取策略选择

根据不同的使用场景选择合适的提取策略：

全文检索：提取所有文本（含表格），拼接为纯文本即可
结构保留：按段落-表格-段落顺序，保留层级关系，转换为 Markdown
样式敏感：保留标题级别、加粗、颜色等样式信息，适用于文档还原
元数据提取：提取页眉页脚、作者、创建时间、修订记录等文档属性

四、批量生成 Word 报告：模板填充与合并邮件

批量生成 Word 文档是办公自动化的高频需求。核心思路是：定义模板结构 + 准备数据源 + 程序填充。

4.1 基于 python-docx 的模板填充

from docx import Document
import json

def fill_template(template_path, data, output_path):
    doc = Document(template_path)

    # 替换段落中的占位符
    for para in doc.paragraphs:
        for key, value in data.items():
            if f"{{{{"{key}"}}}}" in para.text:
                para.text = para.text.replace(f"{{{{"{key}"}}}}", str(value))

    # 替换表格中的占位符
    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                for key, value in data.items():
                    if f"{{{{"{key}"}}}}" in cell.text:
                        cell.text = cell.text.replace(
                            f"{{{{"{key}"}}}}", str(value))

    doc.save(output_path)
    print(f"已生成: {output_path}")

# 使用示例
data = {
    "姓名": "张三",
    "日期": "2026年5月3日",
    "项目名称": "文档自动化系统",
    "负责人": "李四"
}
fill_template('template.docx', data, 'output_report.docx')

4.2 批量生成（合并邮件模式）

import csv
from docx import Document

def batch_generate(template_path, csv_path, output_dir):
    with open(csv_path, 'r', encoding='utf-8') as f:
        reader = csv.DictReader(f)
        for row in reader:
            doc = Document(template_path)
            for para in doc.paragraphs:
                for key, value in row.items():
                    if f"{{{{"{key}"}}}}" in para.text:
                        para.text = para.text.replace(
                            f"{{{{"{key}"}}}}", value)
            filename = f"{row.get('姓名', 'unknown')}_report.docx"
            doc.save(f"{output_dir}/{filename}")
            print(f"已生成: {filename}")

# 提示词示例
# "请帮我写一个Python脚本，从employee.csv读取员工数据，
# 填充到template.docx模板中，为每个员工生成一份单独的Word报告"

提示词示例："我有一个模板文件 template.docx，里面包含 {{姓名}}、{{职位}}、{{部门}} 等占位符。请帮我写一个 Python 脚本，从一个 Excel 文件读取数据，批量生成 Word 文档，每个员工一份，文件名用'员工姓名_报告.docx'格式。"

进阶技巧：保留格式的占位符替换

上面的方法在替换文本时可能会丢失原有格式（如字体、颜色）。如果需要保留格式，需要在 run 级别进行替换：遍历每个段落的 runs，在每个 run 内部替换占位符文本，而不是替换整个 paragraph 的 text。Claude Code 可以帮你实现这种精细化的替换逻辑。

五、Word 转 PDF / Markdown / HTML 的自动化

格式转换是文档处理中另一个常见需求。不同输出格式有各自的工具链和注意事项。

5.1 Word 转 PDF

# 方案一：使用 docx2pdf（需要安装 Microsoft Word 或 LibreOffice）
# pip install docx2pdf
from docx2pdf import convert

convert('input.docx', 'output.pdf')

# 批量转换
import glob
for docx_file in glob.glob('reports/*.docx'):
    pdf_file = docx_file.replace('.docx', '.pdf')
    convert(docx_file, pdf_file)
    print(f"转换完成: {pdf_file}")

# 方案二：使用 LibreOffice 命令行（跨平台，无需安装 Office）
# LibreOffice 为免费开源办公套件
import subprocess

def docx_to_pdf(input_path, output_path):
    cmd = [
        'libreoffice',
        '--headless',
        '--convert-to',
        'pdf',
        '--outdir',
        output_path,
        input_path
    ]
    result = subprocess.run(cmd, capture_output=True, text=True)
    return result.returncode == 0

5.2 Word 转 Markdown

# pip install mammoth
import mammoth

def docx_to_markdown(input_path, output_path):
    with open(input_path, 'rb') as f:
        result = mammoth.convert_to_markdown(f)
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(result.value)
    if result.messages:
        for msg in result.messages:
            print(f"警告: {msg}")
    return result.value

markdown = docx_to_markdown('document.docx', 'document.md')

5.3 Word 转 HTML

# 方案一：使用 mammoth 转换
import mammoth

def docx_to_html(input_path, output_path):
    with open(input_path, 'rb') as f:
        result = mammoth.convert_to_html(f)
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(result.value)

# 方案二：python-docx 自建转换（控制更精细）
def docx_simple_to_html(input_path, output_path):
    doc = Document(input_path)
    html_parts = ['<!DOCTYPE html><html><body>']
    for para in doc.paragraphs:
        if para.style.name.startswith('Heading'):
            level = para.style.name.replace('Heading ', '')
            html_parts.append(f'<h{level}>{para.text}</h{level}>')
        elif para.text.strip():
            html_parts.append(f'<p>{para.text}</p>')
    html_parts.append('</body></html>')
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write('\n'.join(html_parts))

转换工具对比

工具	适用场景	优点	局限
docx2pdf	Word 转 PDF	保真度最高	需安装 Word 或 LibreOffice
mammoth	Word 转 MD/HTML	轻量、纯 Python、结果干净	复杂样式可能丢失
python-docx	所有编辑操作	功能最全、控制最细	学习曲线较陡
pandoc	通用文档转换	格式支持最多	需单独安装 pandoc

六、Docx 文档结构与样式操作

理解 .docx 文档的内部结构，有助于更精准地操控文档样式。

6.1 文档结构层次

一个 .docx 文档的结构可以用以下层次来描述：

Document（文档根对象）-- 包含 Sections
Section（节）-- 控制页边距、页眉页脚、页面方向
Paragraph（段落）-- 包含 Runs，有样式和对齐方式
Run（文本片段）-- 同一格式的连续文本，控制字体、大小、颜色、加粗等
Table（表格）-- 由 Rows 和 Cells 组成

6.2 页面布局与页眉页脚

from docx import Document
from docx.shared import Inches, Cm, Pt
from docx.enum.section import WD_ORIENT

doc = Document()

# 设置页面边距
section = doc.sections[0]
section.top_margin = Cm(2.54)
section.bottom_margin = Cm(2.54)
section.left_margin = Cm(3.17)
section.right_margin = Cm(3.17)

# 设置横向页面
section.orientation = WD_ORIENT.LANDSCAPE
section.page_width = Cm(29.7)
section.page_height = Cm(21.0)

# 添加页眉
header = section.header
header.is_linked_to_previous = False
header_para = header.paragraphs[0]
header_para.text = '内部资料 - 机密文件'
header_para.alignment = 1  # CENTER

# 添加页脚（页码）
footer = section.footer
footer_para = footer.paragraphs[0]
footer_para.alignment = 1
run = footer_para.add_run()
# 注意：页码字段需要用 XML 方式添加
from docx.oxml.ns import qn
fldChar1 = run._r.makeelement(qn('w:fldChar'), {qn('w:fldCharType'): 'begin'})
run._r.append(fldChar1)
instrText = run._r.makeelement(qn('w:instrText'), {})
instrText.text = ' PAGE '
run._r.append(instrText)
fldChar2 = run._r.makeelement(qn('w:fldChar'), {qn('w:fldCharType'): 'end'})
run._r.append(fldChar2)

6.3 标题与段落样式

from docx.enum.style import WD_STYLE_TYPE
from docx.oxml.ns import qn

def create_custom_style(doc, style_name, font_name, font_size, color_hex):
    # 创建自定义段落样式
    style = doc.styles.add_style(style_name, WD_STYLE_TYPE.PARAGRAPH)
    style.font.name = font_name
    style.font.size = Pt(font_size)
    # 对中文字体单独设置
    rPr = style.element.find(qn('w:rPr'))
    if rPr is None:
        rPr = style.element.makeelement(qn('w:rPr'), {})
        style.element.append(rPr)
    rFonts = rPr.makeelement(qn('w:rFonts'), {
        qn('w:eastAsia'): font_name
    })
    rPr.append(rFonts)
    return style

# 使用自定义样式
custom_style = create_custom_style(doc, 'MyStyle', '微软雅黑', 12, '#333333')
para = doc.add_paragraph('这是应用自定义样式的段落')
para.style = custom_style

样式操作的核心原则：在 python-docx 中，字体格式设置在 Run 级别，段落对齐和缩进在 Paragraph 级别，页面布局在 Section 级别。理解这三层分工是精确控制文档样式的关键。Claude Code 可以帮助你以自然语言描述样式需求，然后自动生成对应的 python-docx 代码。

七、从 Excel 数据自动生成 Word 报表的工作流

这是实际工作中最实用的场景之一。下面给出一个完整的工作流示例。

7.1 完整工作流代码

import pandas as pd
from docx import Document
from docx.shared import Inches, Pt, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH
from datetime import datetime

def excel_to_word_report(excel_path, output_path):
    # 1. 读取 Excel 数据
    df = pd.read_excel(excel_path)
    df = df.fillna('')

    # 2. 创建 Word 文档
    doc = Document()

    # 3. 添加封面信息
    title = doc.add_heading('月度销售数据报告', level=0)
    title.alignment = WD_ALIGN_PARAGRAPH.CENTER
    doc.add_paragraph('')
    info = doc.add_paragraph()
    info.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = info.add_run(f'生成日期：{datetime.now().strftime("%Y年%m月%d日")}')
    run.font.size = Pt(14)
    run.font.color.rgb = RGBColor(0x66, 0x66, 0x66)

    # 4. 添加汇总统计
    doc.add_heading('一、数据概览', level=1)
    summary = doc.add_paragraph()
    summary.add_run(f'总记录数：{len(df)} 条').bold = True
    doc.add_paragraph('')

    # 5. 添加数据表格
    doc.add_heading('二、详细数据', level=1)
    table = doc.add_table(rows=len(df) + 1, cols=len(df.columns))
    table.style = 'Medium Shading 1 Accent 1'

    # 表头
    for j, col in enumerate(df.columns):
        table.rows[0].cells[j].text = str(col)

    # 数据行
    for i, row in df.iterrows():
        for j, col in enumerate(df.columns):
            table.rows[i + 1].cells[j].text = str(row[col])

    doc.save(output_path)
    print(f"报告已生成: {output_path}")

# 执行
excel_to_word_report('销售数据.xlsx', '月度销售报告.docx')

工作流自动化管道

将上述流程嵌入到自动化管道中，可以实现定时自动生成报告：

数据源：从数据库/API/Excel 提取数据
数据预处理：用 pandas 清洗、聚合、分析数据
模板填充：将分析结果填入 Word 模板
格式美化：应用样式、添加图表占位
输出分发：保存为 .docx，或进一步转为 PDF
定时任务：用 cron / 任务计划程序定期执行

提示词示例："我有一个 Excel 文件 sales_data.xlsx，里面有'月份'、'产品'、'销售额'、'利润'四列。请帮我写一个 Python 脚本，读取这个 Excel 文件，生成一份 Word 报告，包含标题、数据概览段落和一个完整的表格。要求表格有样式，标题居中，日期显示当前时间。"

八、实际案例：批量生成合同、简历筛选、论文格式整理

以下是三个具有代表性的实际使用案例，展示了 Claude Code 在不同场景下处理 Word 文件的能力。

8.1 案例一：批量生成合同

# 场景：从 Excel 客户数据批量生成合同 Word 文档
# 每个客户生成一份合同，合同编号自动生成

import pandas as pd
from docx import Document
from datetime import datetime

def batch_generate_contracts(excel_path, template_path, output_dir):
    df = pd.read_excel(excel_path)

    for idx, row in df.iterrows():
        doc = Document(template_path)
        contract_no = f"CT-{datetime.now().strftime('%Y%m')}-{idx+1:04d}"

        replacements = {
            '{{合同编号}}': contract_no,
            '{{甲方名称}}': row['公司名称'],
            '{{甲方地址}}': row['公司地址'],
            '{{联系人}}': row['联系人'],
            '{{联系电话}}': str(row['电话']),
            '{{合同金额}}': f"¥{row['金额']:,.2f}",
            '{{签订日期}}': datetime.now().strftime('%Y年%m月%d日')
        }

        # 执行替换（段落级）
        for para in doc.paragraphs:
            for old, new in replacements.items():
                if old in para.text:
                    para.text = para.text.replace(old, new)

        filename = f"{row['公司名称']}_合同_{contract_no}.docx"
        doc.save(f"{output_dir}/{filename}")
        print(f"已生成: {filename}")

# Claude Code 提示词：
# "请帮我写一个批量合同生成脚本。从 customer.xlsx 读取客户数据，
# 使用 contract_template.docx 作为模板，
# 为每个客户生成一份合同。模板中的占位符包括{{合同编号}}、
# {{甲方名称}}、{{合同金额}}等。合同编号规则：CT-年月-序号。"

8.2 案例二：简历筛选与结构化提取

# 场景：从大量 Word 格式简历中提取结构化信息

import os
import re
import json
from docx import Document

def parse_resume(docx_path):
    doc = Document(docx_path)
    full_text = '\n'.join([p.text for p in doc.paragraphs])

    # 使用正则表达式提取关键信息（简易版）
    info = {}

    # 提取姓名（通常在第一行或标题中）
    lines = full_text.split('\n')
    info['姓名'] = lines[0].strip() if lines else ''

    # 提取手机号
    phone_match = re.search(r'1[3-9]\d{9}', full_text)
    info['手机'] = phone_match.group() if phone_match else ''

    # 提取邮箱
    email_match = re.search(r'[\w.+-]+@[\w-]+\.[\w.-]+', full_text)
    info['邮箱'] = email_match.group() if email_match else ''

    return info

# 批量处理简历目录
results = []
for f in os.listdir('resumes/'):
    if f.endswith('.docx'):
        info = parse_resume(os.path.join('resumes/', f))
        info['文件名'] = f
        results.append(info)

# 保存为 JSON 供进一步筛选
with open('resumes_data.json', 'w', encoding='utf-8') as f:
    json.dump(results, f, ensure_ascii=False, indent=2)

print(f"共处理 {len(results)} 份简历")

8.3 案例三：论文格式整理

# 场景：统一整理论文格式（字体、行距、编号）
# 这个脚本由 Claude Code 根据自然语言需求生成

from docx import Document
from docx.shared import Pt, Cm
from docx.enum.text import WD_ALIGN_PARAGRAPH

def format_thesis(input_path, output_path):
    doc = Document(input_path)

    # 统一正文格式
    for para in doc.paragraphs:
        for run in para.runs:
            run.font.name = '宋体'
            run.font.size = Pt(12)

        # 设置行距为1.5倍
        para.paragraph_format.line_spacing = 1.5

        # 首行缩进2字符
        para.paragraph_format.first_line_indent = Cm(0.74)

    # 标题居中并加粗
    for para in doc.paragraphs:
        if para.style.name.startswith('Heading'):
            para.alignment = WD_ALIGN_PARAGRAPH.CENTER
            for run in para.runs:
                run.bold = True

    doc.save(output_path)
    print("论文格式整理完成")

# Claude Code 提示词：
# "请帮我写一个 Python 脚本，整理我的毕业论文格式：
# 1. 正文字体统一为宋体12号、1.5倍行距、首行缩进
# 2. 所有标题居中并加粗
# 3. 页边距设置为上下2.54cm、左右3.17cm"

案例应用的通用模式

以上三个案例展示了 Claude Code 处理 Word 文档的通用模式：自然语言描述需求 -> Claude Code 生成 Python 代码 -> python-docx 执行实际文档操作。无论你是在批量生成合同、筛选简历还是整理论文格式，都可以遵循这一模式。关键是要清晰描述：输入是什么、输出是什么、中间需要哪些处理逻辑。

九、常见问题与跨平台注意事项

问题	原因	解决方案
python-docx 无法读取 .doc 文件	.doc 是旧版二进制格式，与 .docx 不兼容	先用 Word 或 LibreOffice 把 .doc 转为 .docx
占位符替换后丢失字体格式	替换整个 paragraph.text 会清除 run 级格式	在 run 级别逐个替换，保留原有 run 属性
插入的图片位置不准确	python-docx 对图片定位支持有限	使用表格单元格定位图片，或直接操作 XML
中文字体名称不生效	需要同时设置 w:eastAsia 属性	通过 rFonts 元素设置东亚字体名称
Linux 服务器上无法转 PDF	docx2pdf 依赖 Word 或 LibreOffice	安装 LibreOffice 或使用 unoconv 服务
文档包含复杂格式（文本框、图表）	python-docx 不支持这些元素	使用 win32com（仅 Windows）或 aspose-words（商业）

跨平台注意事项

Windows / macOS / Linux 对比

Windows：可使用 win32com 直接操控 Word 应用程序（保真度最高），也可使用 python-docx。docx2pdf 可直接调用 Word 程序。
macOS：python-docx 工作正常。docx2pdf 需要安装 LibreOffice 才能工作。
Linux：python-docx 完全支持。PDF 转换需要使用 LibreOffice 命令行或 unoconv 服务。无法使用 win32com。

核心要点总结

认清能力边界：Claude Code 不直接操作 .docx 文件，但可以编写 python-docx 代码来完成所有文档操作。
掌握 python-docx 基础：理解 Document - Section - Paragraph - Run 的层级结构，这是所有操作的基础。
模板填充是最常用的模式：定义模板 -> 准备数据 -> 程序填充，三步完成批量生成。
格式转换选对工具：docx2pdf（高保真PDF）、mammoth（干净的Markdown/HTML）、python-docx（精细控制）。
跨平台要注意：Linux 服务器上需要额外安装 LibreOffice 来支持 PDF 转换。
Claude Code 提示词是关键：清晰描述输入、输出和处理逻辑，Claude Code 能自动生成完整的解决方案代码。