pandas 的 `excelwriter` 在新版本中已移除直接传入 `options` 的方式，需通过 `engine_kwargs` 传递编码参数；本文详解如何为 xlsxwriter 引擎正确配置 utf-8 支持，避免 `typeerror` 并确保中文等 unicode 字符正常显示。
在使用 pandas 将 DataFrame 导出为 Excel 文件（.xlsx）时，很多用户会误以为可通过 options={'encoding': 'utf-8'} 直接设置编码——尤其在习惯处理 CSV 文件（需显式指定 encoding='utf-8'）后容易产生这种误解。但需明确：标准 .xlsx 文件本身基于 Office Open XML 格式，原生支持 Unicode，无需也不接受 encoding 参数；而报错 TypeError: Workbook.__init__() got an unexpected keyword argument 'encoding' 正是因为 xlsxwriter 引擎根本不支持该选项。
那么，为什么有人会尝试设置 encoding='utf-8'？常见原因包括：
- 曾用 openpyxl 或旧版 xlsxwriter（v1.3.7 以前）的错误文档误导；
- 混淆了 .csv 导出（需 encoding）与 .xlsx 导出（无需）；
- 实际需求其实是确保中文、emoji 等字符正确渲染——而这依赖于字体和引擎兼容性，而非“编码参数”。
✅ 正确做法（针对 xlsxwriter 引擎）：
xlsxwriter 默认即以 UTF-8 内部处理所有字符串，你只需确保使用较新版本（≥1.3.7）并避免传入无效的 encoding 选项。若仍需显式控制（如设置默认字体以增强中文显示），可使用 options 中受支持的键，例如：
import pandas as pd
file_name = "bobs_burgers"
data_table = pd.DataFrame({
"角色": ["Bob", "Linda", "Tina"],
"台词": ["I love burgers!", "You're my little burger!", "Boop boop be doop!"]
})
# ✅ 推荐写法：不传 encoding，仅在必要时配置字体等有效选项
with pd.ExcelWriter(
fr".\Exported_data\{file_name}.xlsx",
engine="xlsxwriter",
engine_kwargs={
"options": {
"default_font": "Microsoft YaHei", # 中文友好字体（Windows）
# "strings_to_numbers": True, # 可选：自动转换数字字符串
}
}
) as writer:
data_table.to_excel(writer, sheet_name="characters", index=False)⚠️ 注意事项：
- engine_kwargs={'options': {...}} 是新版 pandas（≥2.0）中传递底层引擎参数的唯一合法方式，直接传 options= 会报错；
- xlsxwriter 的 options 中没有 encoding 键，传入将触发 TypeError；官方文档明确列出的有效选项见 xlsxwriter Options；
- 若需导出含 BOM 的 UTF-8 CSV，请改用 df.to_csv(..., encoding='utf-8-sig')；
- 如遇中文显示为方框（□），请检查 Excel 中是否安装了对应字体，并在 options 中指定（如 "default_font": "SimSun" 或 "Noto Sans CJK SC"）。
? 总结：对于 .xlsx 导出，无需、也不能设置 encoding='utf-8'；xlsxwriter 和 openpyxl 均原生支持 Unicode。专注升级库版本、合理配置字体与格式，即可稳定导出多语言数据。
