使用docxtpl渲染docx模板时图片丢失问题求助

问题描述 #

使用docxtpl（python-docx-template）从字典渲染Word模板，文本渲染功能正常，但将包含图片的子文档模板渲染为字节流后，通过new_subdoc加载到主文档时，图片完全丢失。主文档模板中已正确定义MODUL_header变量用于插入子文档。

附问题代码：

from io import BytesIO
import os  # 原代码遗漏导入os模块
from docx import Document
from docxtpl import DocxTemplate
from docxcompose.composer import Composer

templates_folder = os.path.join(os.path.dirname(__file__), 'templates')
output_folder = os.path.join(os.path.dirname(__file__), 'output')

test_data = {
    'MODUL_header': {
        'something': 'bla'
    }  # 原代码缺少闭合括号
}


def generate_header(template_path):
    document = DocxTemplate(template_path)
    document.render(test_data)

    file_stream = BytesIO()
    document.save(file_stream)
    file_stream.seek(0)
    return file_stream


def test(template_path):
    with open(template_path, 'rb') as f:
        source_stream = BytesIO(f.read())

    document = DocxTemplate(source_stream)

    if "MODUL_header" in test_data:
        _path = os.path.join(templates_folder, 'header.docx')
        # 原代码函数名错误：generate_kopfzeile应为generate_header
        header = document.new_subdoc(generate_header(_path))
        test_data['MODUL_header'] = header

    document.render(test_data)

    file_path = os.path.join(output_folder, 'test.docx')
    document.save(file_path)


if __name__ == '__main__':
    template_path = os.path.join(templates_folder, 'main_template.docx')
    test(template_path)

可能原因及解决方案 #

1. 代码基础错误 #

• 原代码遗漏os模块导入，test_data字典缺少闭合括号，函数调用时写错函数名（generate_kopfzeile应为generate_header），这些语法错误会导致程序异常，需先修正。

2. 子文档图片资源未被正确复制 #

这是图片丢失的核心原因：
docx格式的图片是嵌入式资源，存储在文档内部的media目录中，且通过XML文件维护引用关系。当你将渲染后的子文档存入BytesIO字节流，再用new_subdoc加载时，docxtpl无法正确解析字节流中的图片资源引用，导致主文档无法关联到图片文件。

针对性解决方案：

• 直接用文件路径创建subdoc：避免通过字节流传递子文档，让new_subdoc直接读取本地已渲染好的子文档文件，这样它能自动处理图片资源的复制与引用。

修改后的核心代码示例：

def generate_header(template_path):
    document = DocxTemplate(template_path)
    # 仅渲染子文档所需的数据，而非全局test_data
    document.render(test_data['MODUL_header'])
    # 先保存到临时文件
    temp_path = os.path.join(output_folder, 'temp_header.docx')
    document.save(temp_path)
    return temp_path


def test(template_path):
    document = DocxTemplate(template_path)

    if "MODUL_header" in test_data:
        _path = os.path.join(templates_folder, 'header.docx')
        temp_header_path = generate_header(_path)
        # 直接传入文件路径创建subdoc
        header = document.new_subdoc(temp_header_path)
        test_data['MODUL_header'] = header
        # 可选：删除临时文件
        os.remove(temp_header_path)

    document.render(test_data)
    file_path = os.path.join(output_folder, 'test.docx')
    document.save(file_path)

• 若必须使用字节流，需手动处理图片资源的复制（提取子文档图片后添加到主文档媒体库并修正引用），但复杂度较高，不推荐。

3. 子文档渲染时机错误 #

原代码中generate_header直接使用全局test_data渲染子文档，可能导致子文档渲染数据不符合预期。应仅传入子文档所需的局部数据（如test_data['MODUL_header']），避免全局数据干扰。

内容的提问来源于stack exchange，提问作者SamPhoenix