使用pandas/openpyxl写入已有Excel后文件损坏如何解决？

问题根因 #

你遇到的文件损坏问题主要由以下几个常见错误导致：

• 使用pd.ExcelWriter的with上下文管理器时，手动调用了writer.save()，with块结束后会自动执行保存和关闭文件操作，重复写入会直接破坏文件结构
• 追加写入xlsx格式文件时没有指定openpyxl引擎，pandas默认引擎不支持xlsx的追加模式
• 操作文件时，目标Excel文件被其他程序（如Excel、WPS）占用，存在读写锁，写入中断导致文件损坏
• 未设置index=False、header=False，多余的索引、表头写入会打乱原有文件结构，也可能触发格式兼容问题

修正方案 #

方案1：pandas写入版本（推荐）

直接使用修正后的写入代码即可：

with pd.ExcelWriter(
    file_loc,
    mode="a",
    engine="openpyxl",  # 必须指定openpyxl作为xlsx格式的写入引擎
    if_sheet_exists="replace"
) as writer:
    marcacoes.to_excel(
        writer,
        sheet_name="MONITORAMENTO",
        startcol=37,
        startrow=5,
        index=False,  # 不写入dataframe索引
        header=False  # 不写入dataframe表头
    )
# 不需要手动调用save()，with上下文会自动处理保存和文件关闭

方案2：openpyxl原生写入版本

操作前务必确认目标Excel文件没有被其他程序打开，优化后的代码如下：

wb = openpyxl.load_workbook(file_loc)
ws = wb["MONITORAMENTO"]
startcol = 37
startrow = 5

for idx, cell_val in enumerate(marcacoes.iloc[:, 0]):
    ws.cell(row=startrow + idx, column=startcol, value=cell_val)

wb.save(file_loc)
wb.close()  # 手动关闭工作簿，彻底释放文件锁

其他排查项 #

如果按照上面修改后依然有问题，先升级依赖库到最新版本，避免旧版本的已知bug：
pip install --upgrade pandas openpyxl

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