看起来你遇到的是python-docx处理图片嵌入时的资源关联故障——虽然文档的XML结构里生成了图片引用，但实际图片文件没被复制到media目录，也没在word/_rels/document.xml.rels里建立映射，导致Word无法加载图片。我来给你梳理几个最可能的修复方向：

1. 先确认图片路径的准确性 #

相对路径很容易踩坑，比如你的脚本运行时的当前工作目录可能和图片所在目录不一致，导致python-docx找不到图片，自然没法复制到media文件夹。建议直接用绝对路径来规避这个问题：

import os
from docx import Document
from docx.shared import Cm

# 把相对路径转为绝对路径
img_full_path = os.path.abspath("test.jpg")
document = Document()
document.add_picture(img_full_path, width=Cm(2.0))
document.save("result.docx")

你可以先打印img_full_path的值，确认它指向的是正确的图片文件位置。

2. 升级python-docx到最新稳定版 #

旧版本的python-docx可能存在图片嵌入的bug，比如某些场景下资源关联逻辑失效。执行下面的命令升级：

pip install --upgrade python-docx

升级后再测试空白文档的插入操作，大概率能解决版本兼容问题。

3. 检查文件权限 #

确保你的脚本有这两个权限：

• 读取test.jpg的权限（比如在Linux/macOS下不要是只读权限，Windows下不要被其他程序锁定）
• 写入输出Word文档以及创建media子目录的权限（比如不要在系统保护的目录下运行脚本，比如C盘根目录）

4. 确保使用标准的空白文档结构 #

如果你是自己手动创建的空白docx文件，可能缺少python-docx需要的基础目录结构（比如_rels文件夹、[Content_Types].xml等）。建议直接用python-docx自带的Document()生成空白文档，而不是打开自己创建的“空文档”：

# 正确的新文档初始化方式
document = Document()
# 而不是打开自定义的空白文档
# document = Document("my_blank.docx")

如果必须用自定义模板，确保模板是从正常Word文档另存为的空白模板，结构完整。

5. 排查图片本身的问题 #

最后确认下test.jpg本身没问题：

• 用图片查看器打开，确认图片没有损坏
• 确保图片格式是python-docx支持的（JPEG、PNG、静态GIF、BMP，不支持WebP等小众格式）

按照这个顺序排查，应该能快速定位到问题所在。

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