dataframe.to_markdown()是最简生成markdown表格的方式，要求pandas 1.0+，需处理中文编码、特殊字符转义、列对齐及缺失值显示等问题。
用 to_markdown() 生成基础 Markdown 表格
直接调用 DataFrame.to_markdown() 是最简方式，它默认输出符合 GitHub Flavored Markdown 规范的表格。注意：该方法在 Pandas 1.0+ 才内置，旧版本需安装 tabulate 并手动导入——否则会报 AttributeError: 'DataFrame' object has no attribute 'to_markdown'。
- 不传参时，表头为列名，对齐方式为左对齐，缺失值显示为
NaN - 若数据含中文列名或内容，确保 Python 环境编码为 UTF-8（尤其 Windows 控制台），否则可能乱码
- 想省略索引列？加参数
index=False；想禁用表头？用headers=[]（但列数需与数据匹配）
控制对齐、缺失值和列宽
to_markdown() 不支持直接设置列宽或自动换行，但可通过 colalign 参数统一指定各列对齐方式（'left' / 'center' / 'right'），而缺失值显示由 na_rep 控制。
-
colalign长度必须等于列数，例如三列数据写成colalign=['left', 'center', 'right'] -
na_rep='—'比默认NaN更适合报表场景；设为空字符串na_rep=''可留白 - 列宽靠人工截断或预处理字段（如用
df[col].str.slice(0, 20) + '...'），to_markdown()本身不处理溢出
嵌入 HTML 或导出到文件时的注意事项
Markdown 表格本身是纯文本，但若需插入到 HTML 页面或 Jupyter Notebook 中，要注意渲染环境是否支持原生解析——部分静态站点生成器（如 MkDocs）要求表格前后有空行，否则可能被当作文本渲染。
- 写入文件时建议用
with open('out.md', 'w', encoding='utf-8') as f: f.write(df.to_markdown())，显式指定编码 - 在 Jupyter 中直接
print(df.to_markdown())不会渲染为表格，需配合IPython.display.Markdown使用 - 若 DataFrame 含特殊字符（如
|、*），to_markdown()不自动转义，可能破坏表格结构，建议提前用df.replace({'|': '\|'}, regex=True)处理
替代方案：手动拼接更可控但需谨慎
当 to_markdown() 无法满足定制需求（比如合并单元格、添加分隔线、动态列标题），就得手写 Markdown 字符串。但这容易出错，尤其列数变化时表头与分隔符长度不匹配会导致渲染失败。
- 表头行与分隔行必须列数一致，例如 3 列就得写
|---|---|---|，少一个|就失效 - 每行末尾的
|建议保留，某些解析器（如 Obsidian）依赖它识别表格边界 - 大量数据时不推荐手写——性能差且难维护，优先考虑先用
to_markdown()输出，再用正则做轻量后处理
to_markdown(index=False, na_rep='—') 就够了；真正卡住的往往是中文对齐异常、管道符冲突，或者忘了检查 Pandas 版本。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
