xlwings调用Excel宏需满足Windows系统、.xlsm文件、宏为Public且路径正确；宏执行后需手动刷新并避免交互操作，参数传递须注意VBA类型匹配与数组下标。
xlwings 调用 Excel 宏必须启用 COM 且宏需在 .xlsm 文件中
xlwings 本身不解析或执行 VBA 代码，它通过 Windows COM 接口让 Python 控制 Excel 进程，因此调用 Application.Run 前必须满足两个硬性条件：运行环境是 Windows（macOS 不支持 COM）、Excel 文件后缀为 .xlsm（普通 .xlsx 无法保存宏）。常见错误是把宏存成 .xlsx 后反复尝试 app.api.Run("Module1.MyMacro")，结果报错 pywintypes.com_error: (-2147352567, 'Exception occurred.', ...) —— 实际上不是权限问题，而是 Excel 根本没加载该宏模块。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用 Excel 手动另存为 → 选择“Excel 启用宏的工作簿 (*.xlsm)”
- 确保宏所在模块未被设为
Private，函数声明为Public Sub MyMacro() - Python 中调用时路径写法要严格：若宏在
ThisWorkbook模块，用"ThisWorkbook!MyMacro"；若在Module1，用"Module1.MyMacro"
数据同步不能依赖宏内部 Range 操作，要用 xlwings 的 range 接口桥接
很多用户以为只要宏跑完，Python 就能立刻读到新数据，结果 sht.range("A1").value 还是旧值。这是因为宏可能操作的是 Excel UI 层的单元格，而 xlwings 的 range 对象缓存了上次读取的状态，且宏执行期间 Python 并未主动刷新引用。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 宏执行完后加一句
app.api.Calculate()（强制重算）和sht.api.Activate()（激活工作表），再读取 - 更可靠的做法是：宏只做逻辑处理，把结果写入固定命名区域（如
Results），Python 用sht.range("Results").options(ndim=2).value显式读取 - 避免在宏里用
Selection或ActiveCell—— xlwings 没有“当前选中”上下文，这类操作在自动化中不可靠
xlwings 与 Excel 进程生命周期不一致，容易导致“宏已运行但 Python 卡住”
典型现象是调用 app.api.Run(...) 后程序无响应，任务管理器里能看到 Excel 进程仍在运行。根本原因是宏内部弹出消息框（MsgBox）、等待用户输入（InputBox）或触发了 Workbook_Open 等事件——这些在无人值守环境下会永久挂起。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 所有宏开头加
Application.DisplayAlerts = False和Application.EnableEvents = False，结尾恢复 - 彻底移除
MsgBox，改用写日志到指定单元格（如Sheets("Log").Range("A1").Value = "Done"），Python 再轮询该单元格 - 启动 Excel 时用
app = xw.App(visible=False)，但注意：visible=False下部分 UI 相关宏（如图表渲染）可能异常，必要时设为True并配合time.sleep()等待
传递参数给 VBA 宏要注意类型映射和数组维度
xlwings 支持向 Application.Run 传参，但 VBA 函数签名必须严格匹配。比如 Python 传 app.api.Run("MyMacro", "hello", 42)，VBA 必须声明为 Public Sub MyMacro(text As String, num As Long)。最常踩的坑是数组：Python 的 [[1,2],[3,4]] 传过去，VBA 接收为 1-based 二维 Variant 数组，UBound(arr, 1) 返回 2（不是 0），且不能直接用 arr(0,0)。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 字符串参数统一用
str()显式转换，避免None或float('nan')导致 VBA 报错 - 传数组时，在 VBA 中用
Dim arr As Variant: arr = param接收，再用LBound(arr, 1)和UBound(arr, 1)遍历 - 如果宏只需返回一个值，别用
Function，改用Sub+ 写入单元格，Python 再读取——VBA Function 返回值在 xlwings 中有时类型丢失
Run 调用上。先保证宏能在 Excel 后台静默跑完，再考虑数据怎么来回。 
