如何在使用 pandas 保存 Excel 文件时正确设置 UTF-8 编码

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。专注升级库版本、合理配置字体与格式，即可稳定导出多语言数据。

# 可选  # 也不  # excel  # windows  # 人会  # 多语言  # 并在  # 只需  # 文档  # 新版本  # 不支持  # win  # microsoft  # word  # go  # 编码  # xml  # 字符串  # 报错  # 为什么  # bom  # office  # csv  # pandas  # 而这 

相关栏目： <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 AI推广<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 SEO优化<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 技术百科<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 谷歌推广<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 百度推广<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 网络营销<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 案例网站<？ｍｕｍａ echo $count; ?> 】 <？ｍｕｍａ $count = M('archives')->where(['typeid'=>$field['id']])->count(); ?> 【 精选文章<？ｍｕｍａ echo $count; ?> 】