生成Excel表格时遭遇OverlappingRange错误，求解决方案

错误原因定位 #

从报错信息xlsxwriter.exceptions.OverlappingRange: Merge range 'B1:E1' overlaps previous merge range 'B1:E1'可以明确：同一个单元格范围B1:E1被重复执行了合并操作。

具体修复步骤 #

1. 移除冗余的无效代码 #

你的代码中有一段永远不会触发的条件分支，不仅毫无作用，还可能引发潜在冲突：

if merged_data_one_range == 'B1:B1':
    ws.write('B1',self.header_name, workbook.add_format({"bold": 1, "border": 1, "align": "left", "valign": "vcenter", 'font_size': 20 if len(df.columns.tolist())>4 else 14}))        

根据当前merged_data_one_range的计算逻辑（有列时为B1:E1，无列时为B1:G1），这个条件永远不会成立，直接删除这段代码即可。

2. 避免重复执行合并操作 #

检查代码调用逻辑：

• 确认生成Excel的代码是否被循环调用，或者同一个工作表对象ws是否被多次执行合并B1:E1的操作。
• 如果需要多次生成同一个工作表，确保每次创建全新的ExcelWriter实例（xlsxwriter不支持修改已存在的工作表内容，复用旧对象会导致重复操作）。

3. 优化合并范围的动态计算逻辑 #

当前代码中merged_data_one_range固定为B1:E1，无法适配不同列数的DataFrame，建议改为根据列数动态计算结束列，避免范围不匹配的问题：

# 替换原merged_data_one_range的计算代码
if df.columns.tolist():
    # 确保alphabet_list包含足够的列字母（如A,B,C...）
    end_col = alphabet_list[len(df.columns.tolist())-1]
    merged_data_one_range = f"B1:{end_col}1"
    merged_data_range = f"B2:{end_col}2"
    conditional_format_range = f"A3:{end_col}3"
else:
    merged_data_one_range = "B1:G1"
    merged_data_range = "B2:G2"
    conditional_format_range = "A3:I3"

4. 验证DataFrame写入的表头设置 #

你的代码中df.to_excel(startrow=2)默认会将DataFrame的表头写入第3行（索引2），如果不需要这个自动生成的表头，建议添加header=False参数，避免表头与自定义内容冲突：

df.to_excel(
    writer,
    index=False,
    startrow=2,
    sheet_name=self.sheet_name,
    header=False  # 不需要自动生成表头时添加
)

修复后的完整代码示例 #

df.to_excel(
    writer,
    index=False,
    startrow=2,
    sheet_name=self.sheet_name,
    header=False  # 根据需求选择是否添加
)
ws = writer.book.get_worksheet_by_name(self.sheet_name)
ws.freeze_panes(3, 0)
workbook = writer.book

merge_head_size = workbook.add_format(
    {"bold": 1, "border": 1, "align": "left", "valign": "vcenter", 'font_size': 20 if len(df.columns.tolist())>4 else 14}) 
merge_sub_head_size = workbook.add_format(
    {"bold": 1, "border": 1, "align": "left", "valign": "vcenter", 'font_size': 10})                                

# 动态计算合并范围
if df.columns.tolist():
    end_col = alphabet_list[len(df.columns.tolist())-1]
    merged_data_one_range = f"B1:{end_col}1"
    merged_data_range = f"B2:{end_col}2"
    conditional_format_range = f"A3:{end_col}3"
else:
    merged_data_one_range = "B1:G1"
    merged_data_range = "B2:G2"
    conditional_format_range = "A3:I3"

blue_background_format = workbook.add_format({'bg_color': '#00b0f0'})
ws.conditional_format(conditional_format_range, {'type': 'no_errors', 'format': blue_background_format})

# 仅执行一次合并操作
ws.merge_range(merged_data_one_range, self.header_name, merge_head_size)
ws.merge_range(merged_data_range, self.sub_headings, merge_sub_head_size)  

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