xlwings是Python与Excel实时交互最直接可控的方式，适合读写公式、调用VBA、操作图表等场景；需注意跨平台差异、Excel进程生命周期管理、单元格读写类型陷阱、VBA调用错误捕获及macOS权限超时问题。
xlwings 是 Python 与 Excel 实时交互最直接、最可控的方式，尤其适合需要读写公式、调用 VBA、操作图表或保持 Excel 进程常驻的场景；它不依赖 COM 自动化（Windows-only）的底层限制，跨平台支持良好，但必须注意 Excel 应用实例的生命周期管理。
如何启动并连接到 Excel 应用实例
xlwings 默认每次 App() 都新建一个 Excel 进程，容易造成“幽灵进程”堆积。实际使用中应优先复用已有实例或显式控制启停。
- 用
App(visible=False, add_book=False)启动隐藏、不建空白工作簿的实例，避免干扰用户界面 - 若要连接已打开的 Excel，用
App(ready=True)（仅 Windows）或遍历apps列表匹配窗口标题（macOS/Linux 需额外判断） - 务必在脚本退出前调用
app.quit()，否则后台 Excel 进程会残留——这是最常见的资源泄漏点
如何安全读写单元格，避开 .value 的陷阱
range.value 看似方便，但默认行为在不同平台、不同数据类型下差异极大：空单元格可能返回 None、np.nan 或空字符串；日期可能转成 datetime 或 float；大范围读取时性能骤降。
- 读取前先用
range.options(ndim=2).value强制二维列表输出，避免一维/标量意外降维 - 写入含时间的数据时，加
options(dates=datetime)显式指定格式，否则 macOS 上可能写成浮点序列号 - 批量写入优先用
range.value = [[...], [...]]而非循环赋值单个 cell，性能差 10 倍以上
如何调用 VBA 函数并捕获错误
xlwings 允许从 Python 直接运行 Excel 中定义的 VBA 函数，但 VBA 错误不会自动抛为 Python 异常，而是静默失败或返回 None。
Python 编程规范
下载
Python 编程规范与最佳实践。强制 PEP 8 代码风格、语法校验、单元测试执行，适用于代码编写、审查和重构。触发词：Python、代码规范、py_compile、单元测试。
立即学习“Python免费学习笔记（深入）”；
- VBA 函数必须声明为
Public且位于标准模块（非 Sheet 或 ThisWorkbook），否则app.api.Run("MyFunc")找不到 - 用
app.api.Run("MyFunc", arg1, arg2)调用，参数类型需与 VBA 声明严格一致（如 VBA 的Long不能传 Pythonfloat） - 捕获错误需在 VBA 中用
On Error GoTo err_handler并通过Application.Caller.Value = "ERROR: ..."回传，Python 侧再检查返回值
如何避免 macOS 上的 AppleScript 权限和超时问题
macOS 版 xlwings 依赖 AppleScript 通信，首次运行会弹窗请求“辅助功能”权限，且默认 5 秒超时，网络延迟或 Excel 卡顿时极易触发 TimeoutError。
- 首次部署前手动在「系统设置 → 隐私与安全性 → 辅助功能」中添加 Terminal / VS Code / Python 进程
- 延长超时：初始化时设
App(script_timeout=30) - 避免在循环中频繁创建/销毁
App实例——macOS 启动 Excel 比 Windows 慢得多，复用实例更稳定
真正难的不是调用某个函数，而是理解 xlwings 在不同平台下对 Excel 进程、内存引用、类型转换的隐式约定；这些细节不报错，但会让脚本在同事电脑上突然失效，或在批量处理时悄悄丢数据。
