在自动化报表和数据处理场景中，经常需要把Python程序计算出的结果按行写入已有的Excel文件。xlwings作为桥接Python与Excel的库，能够直接操控工作簿、工作表和单元格区域，特别适合需要保留原表格格式或借助Excel公式的场景。与单纯读取修改文件的库不同，xlwings可以连接正在运行的Excel进程，也可以自行启动一个隐式实例，从而让数据插入过程更贴近真实办公操作。
一、环境准备与基础对象模型
在开始写代码前，需要先安装xlwings库。可以通过pip命令完成：在终端执行 pip install xlwings 即可。安装完成后，建议在代码开头导入该库，并根据需求决定是否让Excel界面可见。如果是在服务器或无桌面环境运行，应当保持不可见以提升执行效率；如果是在开发调试阶段，打开可见性能帮助观察数据是否插入到了正确位置。
xlwings的核心对象层级是：App代表Excel应用程序，Book代表工作簿，Sheet代表工作表，Range代表单元格区域。按行循环插入数据时，我们通常先获取目标Sheet，再确定起始行号，随后通过循环把每条记录写入连续的行中。理解这一层级关系，才能准确调用对应方法，避免出现“找不到工作表”或“索引越界”的报错。
下面是一段最基础的连接与定位代码，展示了如何打开已有文件并选定工作表：
import xlwings as xw # 启动Excel应用，visible=False表示后台运行 app = xw.App(visible=False, add_book=False) # 打开已有工作簿，注意路径中使用原始字符串避免转义问题 wb = app.books.open(r'C:datareport.xlsx') # 选择第一个工作表 sheet = wb.sheets[0] # 假设从第2行开始插入（第1行是表头） start_row = 2
二、按行循环插入单条与批量数据
所谓“按行循环插入”，本质是用一个for循环遍历数据列表，每取一条记录就向sheet的某一行写入多个单元格。最简单的做法是利用Range对象的api属性或直接用偏移。例如，对每条数据使用 sheet.range(row, col).value = item 逐个赋值。这种方式直观，但当列数较多时代码会显得冗长，因此更推荐把一整行数据作为列表一次性赋给某一行区域。
如果我们有一组用户数据，每条包含姓名、年龄、城市三个字段，可以用如下方式循环写入。注意行号要在每次循环后自增，否则所有数据会覆盖在同一行。同时，若原文件已有N行数据，我们应当从N+1行开始，而不是固定从某行开始，这需要通过 sheet.used_range.last_cell.row 来动态获取已有行数。
以下示例演示了从最后一行之后追加数据，并确保每行三个字段正确落位：
import xlwings as xw
app = xw.App(visible=False, add_book=False)
wb = app.books.open(r'C:datareport.xlsx')
sheet = wb.sheets['Sheet1']
# 动态获取最后一行
last_row = sheet.used_range.last_cell.row
start_row = last_row + 1
# 待插入的数据列表
records = [
['张三', 28, '北京'],
['李四', 34, '上海'],
['王五', 22, '广州']
]
for i, row_data in enumerate(records):
# 计算当前行号
cur_row = start_row + i
# 将整行数据写入：从第1列到第三列
sheet.range((cur_row, 1)).value = row_data
wb.save()
wb.close()
app.quit()
上述写法的优点是逻辑清晰，每次循环只操作一次Range赋值，性能在千行级别内完全可以接受。如果数据量达到数万行，可以考虑先把所有记录拼成一个二维列表，然后用 sheet.range((start_row,1), (end_row,3)).value = big_list 一次性写入，这样能显著减少Python与Excel之间的通信次数。
三、插入位置控制与常见避坑点
实际业务中，往往不是简单追加，而是要在指定行“插入”而非“覆盖”。Excel并没有直接提供单条插入行的简易Python方法，但可以通过调用api来插入整行：sheet.api.Rows(row_index).Insert()。插入后，原该行及下方内容自动下移，此时再写入新数据就不会丢失历史信息。需要特别小心的是，如果循环是从上往下插入，每插一次下方行号都会变化，因此建议从下往上插，或每次插入后重新计算目标行。
另一个常见坑是Excel进程未正确关闭。使用 app.quit() 之前必须保证 wb.close() 且 wb.save() 已执行，否则文件可能被锁定，下次打开会提示“文件已被其他用户占用”。在脚本结尾使用try-finally结构能有效避免异常退出导致的进程残留。此外，xlwings默认会新建一个Excel实例，若系统中已有一个手动打开的Excel，二者互不影响，但在自动化任务中最好统一用不可见实例以防干扰。
最后要注意数据类型与公式的差异。如果单元格原本是公式，直接用value赋值会覆盖公式；若希望保留公式仅填入参数，应当操作其他辅助列。下面示例展示了如何在第3行上方插入一空行并写入表头式数据，同时避免行号错乱：
import xlwings as xw app = xw.App(visible=False, add_book=False) wb = app.books.open(r'C:datareport.xlsx') sheet = wb.sheets[0] insert_at = 3 # 在第3行位置插入一整行，原第3行下移 sheet.api.Rows(insert_at).Insert() # 写入新行数据 sheet.range((insert_at, 1)).value = ['新姓名', 30, '深圳'] wb.save() wb.close() app.quit()
通过以上三种不同维度的操作，我们可以灵活应对“追加写”“指定行覆盖写”以及“真正插入行”的需求。结合动态获取行号、批量赋值与进程管理，便能在生产环境中稳定地使用Python xlwings完成Excel按行循环插入数据的任务。