CSV 转 Markdown 表格指南：贴进 README 之前先检查竖线

Markdown 表格的语法很脆弱：一个没转义的竖线、一个单元格内换行，就能让整张表错位。生成之后一定要看预览。

把表格贴进文档

写 README 时列出参数、在文档里放一张对比表、在 PR 描述里贴测试结果、把 Excel 的一小块复制到博客——手动画分隔线又慢又容易数错列，转换一下省事很多。

从 Excel 或 Numbers 复制出来的内容默认是制表符分隔，正好适合直接粘贴；从 CSV 文件来的则是逗号分隔。两种都支持，按来源选就行，选错了列会当场错位。

第一行是表头，其余行是数据，工具会自动补一行 --- 作为分隔线。单元格里含逗号时，改用制表符分隔，否则列会被切开；从表格软件直接复制通常就是制表符，最稳，也最不容易出错。

单元格里出现竖线 | 时，必须手动转义成 \|，否则 Markdown 会把它当成列边界，整行错位。工具不会自动处理这一点，生成后要自己检查。单元格内也不能有换行，有的话先合并成一行。

Markdown 表格不支持合并单元格、嵌套表格和跨行跨列，长文本也不会自动换行，列宽由渲染器决定。需要复杂排版时，HTML 的 table 或文档格式更合适，硬塞进 Markdown 只会难维护。

列数不一致时，多出的单元格会被拼接、缺少的会留空，渲染出来的表格看着像错的。生成前先在表格软件里把列补齐，生成后再看一次预览，比事后逐行修快，也更不容易漏，不同渲染器结果还可能略有差异。

为什么生成的表格列错位了？

多数是分隔符选错：内容里本来就有逗号，却仍用逗号分隔。改用制表符，或给含逗号的字段加引号后再转换；也要检查每行列数是否一致。

单元格里想写竖线怎么办？

把竖线写成反斜杠加竖线，让 Markdown 知道它是内容而不是列边界。工具不做自动转义，生成后需要手动替换一遍再提交。

能合并单元格吗？

不能。Markdown 表格语法不支持合并，也没有跨行跨列的概念。确有需要时改用 HTML table，或把内容拆成多张小表。