解决 docxtpl 渲染 Word 文档时图片丢失的问题

霞舞

发布时间：2025-08-24 22:52:31

439人浏览过

来源于php中文网

原创

解决 docxtpl 渲染 word 文档时图片丢失的问题

在使用 docxtpl (python-docx-template) 渲染 Word 文档时，图片丢失的问题通常是由于 Word 文档内部的图片 ID 冲突造成的。为了解决这个问题，我们需要深入了解 Word 文档的内部结构，并找到冲突的 ID。

诊断图片丢失问题

当使用 docxtpl 渲染 Word 文档时，如果发现图片丢失，可以按照以下步骤进行诊断：

解压 .docx 文件： .docx 文件实际上是一个压缩包，可以使用 7-Zip 或其他解压工具将其解压。
检查内部 XML 文件： 解压后，你会看到多个文件夹和 XML 文件。我们需要关注以下两个文件：
- word/document.xml: 包含文档正文的内容。
- word/header.xml (或 word/footer.xml): 包含页眉或页脚的内容。如果存在多个页眉或页脚，可能会有 header1.xml、header2.xml 等。
查找图片 ID： 在 document.xml 和 header.xml (以及其他页眉/页脚文件) 中，查找与图片相关的 XML 元素，通常是元素。在该元素中，会有一个 r:embed 属性，其值类似于 rId8。这个 rId8 就是图片的 ID。
确认 ID 是否冲突： 检查 document.xml 和所有 header.xml 文件，确认是否存在相同的 rId 值。如果发现相同的 rId 出现在不同的文件中，那么就存在 ID 冲突，这很可能导致图片丢失。

解决 ID 冲突

一旦确认存在 ID 冲突，可以采取以下方法解决：

手动修改 XML 文件： 这是最直接的方法，但需要小心操作。
- 找到冲突的 rId。
- 在一个文件中（例如 header.xml），将冲突的 rId 修改为新的、唯一的 ID（例如 rId99）。
- 同时，需要修改所有引用该 rId 的地方，确保它们指向新的 ID。
- 修改完成后，重新压缩所有文件和文件夹，并将扩展名改回 .docx。
注意： 手动修改 XML 文件容易出错，建议在修改前备份原始文件。
重新插入图片： 更安全的方法是在 Word 中重新插入图片。

Notion Sites
Notion 推出的AI网站构建工具，允许用户将 Notion 页面直接发布为完整网站。

下载
- 删除原始图片。
- 重新插入图片。Word 会自动分配新的、唯一的 ID。
- 保存文档。

使用编程方法避免冲突： 如果你需要通过编程方式生成包含多个子文档的 Word 文档，可以考虑在合并文档之前，预先处理每个子文档，确保它们的图片 ID 不会冲突。以下是一个示例代码，展示了如何使用 lxml 库来修改 Word 文档中的图片 ID：

from docx import Document
from docxcompose.composer import Composer
from lxml import etree
import zipfile
import os

def fix_image_ids(docx_path, id_offset):
    """
    修复 Word 文档中的图片 ID，避免冲突。

    Args:
        docx_path (str): Word 文档的路径。
        id_offset (int): ID 偏移量，用于生成新的 ID。
    """
    # 解压 docx 文件
    with zipfile.ZipFile(docx_path, 'r') as zip_ref:
        zip_ref.extractall("temp_docx")

    # 解析 document.xml 文件
    tree = etree.parse("temp_docx/word/document.xml")
    root = tree.getroot()

    # 定义命名空间
    namespaces = {
        'a': 'http://schemas.openxmlformats.org/drawingml/2006/main',
        'r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships'
    }

    # 查找所有 blipFill 元素
    blip_fills = root.xpath('//a:blipFill', namespaces=namespaces)

    for blip_fill in blip_fills:
        # 获取 r:embed 属性值 (例如 rId8)
        embed_attr = blip_fill.xpath('./a:blip/@r:embed', namespaces=namespaces)[0]
        old_id = int(embed_attr[3:])  # 提取数字部分 (例如 8)
        new_id = old_id + id_offset
        new_embed_attr = f"rId{new_id}"

        # 更新 r:embed 属性
        blip_fill.xpath('./a:blip', namespaces=namespaces)[0].set('{http://schemas.openxmlformats.org/officeDocument/2006/relationships}embed', new_embed_attr)

    # 保存修改后的 document.xml
    tree.write("temp_docx/word/document.xml", encoding="utf-8", xml_declaration=True)

    # 修改 .rels 文件
    rels_path = "temp_docx/word/_rels/document.xml.rels"
    if os.path.exists(rels_path):
        rels_tree = etree.parse(rels_path)
        rels_root = rels_tree.getroot()

        for relationship in rels_root.xpath('//Relationship'):
            old_id_rel = relationship.get('Id')
            old_id_num = int(old_id_rel[3:])
            new_id_num = old_id_num + id_offset
            new_id_rel = f"rId{new_id_num}"
            relationship.set('Id', new_id_rel)

        rels_tree.write(rels_path, encoding="utf-8", xml_declaration=True)

    # 重新压缩 docx 文件
    with zipfile.ZipFile(f"fixed_{os.path.basename(docx_path)}", 'w', zipfile.ZIP_DEFLATED) as zipf:
        for root, dirs, files in os.walk("temp_docx"):
            for file in files:
                zipf.write(os.path.join(root, file), os.path.relpath(os.path.join(root, file), "temp_docx"))

    # 清理临时文件夹
    import shutil
    shutil.rmtree("temp_docx")

# 示例用法
if __name__ == '__main__':
    # 创建两个示例 Word 文档
    doc1 = Document()
    doc1.add_paragraph("Document 1 with an image.")
    doc1.add_picture("example.png") # 确保 example.png 存在
    doc1.save("doc1.docx")

    doc2 = Document()
    doc2.add_paragraph("Document 2 with an image.")
    doc2.add_picture("example.png") # 确保 example.png 存在
    doc2.save("doc2.docx")

    # 修改 doc2.docx 的图片 ID，偏移量为 100
    fix_image_ids("doc2.docx", 100)

    # 合并文档
    master_document = Document("doc1.docx")
    composer = Composer(master_document)
    composer.append(Document("fixed_doc2.docx"))
    composer.save("merged_document.docx")

    print("文档已合并，并修复了图片 ID 冲突。")

代码解释：