我之前也踩过一模一样的坑——用python-docx给页眉加图后，正文第一张图在Office 365里死活不显示，还弹出文件修复提示，但LibreOffice却能正常看到。本质原因是python-docx在混合处理同一Run里的文本和多张图片时，生成的XML资源ID出现了冲突，Office 365对这种不规范的XML容忍度很低，而LibreOffice的容错性更强。

下面是具体的修复方案和优化后的代码：

核心修复思路 #

• 不要在同一个Run对象里混合添加文本和多张图片，Office对这种结构的解析非常严格
• 页眉的图片和正文的图片要分开在独立的段落/Run中，避免资源引用冲突

优化后的代码 #

from docx import Document as DocumentDocx
from docx.shared import Cm

file_list = ['i1', 'i2', 'i3', 'i4']
document = DocumentDocx()
section = document.sections[0]
header = section.header

# 页眉图片单独放在独立的段落和Run中
header_paragraph = header.add_paragraph()
header_run = header_paragraph.add_run()
header_run.add_picture('logo.png', height=Cm(1))

# 正文标题单独占一个段落的Run
title_paragraph = document.add_paragraph()
title_paragraph.alignment = 1  # 设置居中对齐
title_run = title_paragraph.add_run('1')

# 遍历图片列表，每个序号+图片放在独立的段落中
for idx, filename in enumerate(file_list):
    # 创建新段落存放当前序号和图片
    content_paragraph = document.add_paragraph()
    content_paragraph.alignment = 1  # 保持和标题一致的居中样式
    
    # 先添加序号文本
    text_run = content_paragraph.add_run(str(idx))
    # 再添加图片，用当前段落的新Run
    img_run = content_paragraph.add_run()
    img_run.add_picture(f'{filename}.png', width=Cm(12))

document.save('fixed_file.docx')

关键改动说明 #

1. 页眉部分：专门为页眉图片创建独立的段落和Run，确保图片资源被正确注册到文档的媒体库中，不会和正文资源混淆
2. 正文部分：
   • 把标题文本单独放在一个段落里，避免和后续图片的Run混合
   • 每个序号和对应的图片都放在新的段落中，即使放在同一段落，也用不同的Run分别处理文本和图片，彻底避免单个Run中混合多个媒体元素导致的XML结构错误
3. 移除了原代码中在同一个Run里连续多次调用add_text和add_picture的操作，这种操作很容易让python-docx生成不符合Office规范的XML标记

这样修改后，生成的DOCX文档在Office 365里就能正常显示所有图片，也不会再弹出修复提示了。

内容的提问来源于stack exchange，提问作者Clément v