CSV 是几乎所有工具的默认导出格式——电子表格、数据库、分析平台，导出时都是 CSV。但写 README、提 GitHub Issue、编写技术文档时，你需要的是 Markdown 表格。手工把 CSV 转成 Markdown 表格既繁琐又容易出错。这篇文章讲清楚 Markdown 表格格式、CSV 边界情况的处理，以及如何在线快速转换。

立即把 CSV 转成 Markdown 表格 →

Markdown 表格格式

Markdown 表格由三部分组成：

| 列 A | 列 B | 列 C |
|------|------|------|
| 值 1 | 值 2 | 值 3 |
| 值 4 | 值 5 | 值 6 |

规则：

  • 第一行是表头。
  • 第二行（分隔行）用连字符 --- 组成，冒号控制对齐。
  • 每一行必须有相同数量的单元格，用 | 分隔。

列对齐

分隔行决定列的对齐方式：

| 左对齐   | 居中     | 右对齐   |
|:--------|:-------:|--------:|
| 文字    | 文字    | 文字    |
语法对齐方式
---左对齐（默认）
:---左对齐（显式）
:---:居中
---:右对齐

数字列用右对齐，扫起来更清晰。

CSV → Markdown 表格：示例

基础转换

输入 CSV：

姓名,角色,团队
Alice,工程师,平台
Bob,设计师,产品
Charlie,经理,增长

输出 Markdown：

| 姓名    | 角色   | 团队 |
|---------|--------|------|
| Alice   | 工程师 | 平台 |
| Bob     | 设计师 | 产品 |
| Charlie | 经理   | 增长 |

效果：

姓名角色团队
Alice工程师平台
Bob设计师产品
Charlie经理增长

含逗号的字段

CSV 用双引号处理值中包含逗号的情况：

城市,描述
北京,"中国首都，政治中心"
上海,"中国最大城市，金融中心"

转换工具会去掉引号，并对值中的竖线（|）进行转义，保证 Markdown 表格结构正确。

数字列

带数字的表格，右对齐数字列让可读性大幅提升：

商品,单价,数量
键盘,299.00,50
鼠标,129.00,120
耳机,499.00,30

右对齐数字列的输出：

| 商品 |   单价 | 数量 |
|------|-------:|-----:|
| 键盘 | 299.00 |   50 |
| 鼠标 | 129.00 |  120 |
| 耳机 | 499.00 |   30 |

空单元格

CSV 中缺失的值在 Markdown 表格里变成空单元格：

id,姓名,邮箱
1,Alice,alice@example.com
2,Bob,
3,,charlie@example.com

输出：

| id | 姓名  | 邮箱              |
|----|-------|-------------------|
| 1  | Alice | alice@example.com |
| 2  | Bob   |                   |
| 3  |       | charlie@example.com |

典型使用场景

GitHub README

GitHub 在 README、Wiki、Issue 里原生渲染 Markdown 表格。把 CSV 粘贴进转换工具，复制 Markdown，直接放进 README 就行。

API 文档

文档里要列出请求参数或响应字段？从电子表格导出 CSV，转成 Markdown，粘贴进文档。比手工格式化表格快得多。

GitHub Issue 和 PR

提 Bug 时带上测试结果、基准对比、配置参数——Markdown 表格比一大块 CSV 代码块可读性强多了。

语雀、飞书文档、Notion

这些平台都支持粘贴时识别 Markdown。转好 Markdown 表格，粘贴进去，直接渲染成表格。

静态文档站

Docusaurus、VitePress、MkDocs 都渲染 Markdown 表格。在电子表格里维护数据，导出 CSV，转换，粘贴进文档即可。

值中含竖线的处理

竖线 | 是 Markdown 表格的分隔符。如果 CSV 值里包含竖线，输出时必须转义为 \|：

快捷键,操作
Cmd|Ctrl+C,复制
Cmd|Ctrl+V,粘贴

转换后：

| 快捷键      | 操作 |
|-------------|------|
| Cmd\|Ctrl+C | 复制 |
| Cmd\|Ctrl+V | 粘贴 |

好的转换工具会自动处理这种情况。

用代码转换

JavaScript

function csvToMarkdown(csv, alignRight = []) {
  const lines = csv.trim().split('\n');
  const rows = lines.map(line =>
    line.split(',').map(cell =>
      cell.trim().replace(/^"|"$/g, '').replace(/\|/g, '\\|')
    )
  );

  const headers = rows[0];
  const separator = headers.map((_, i) =>
    alignRight.includes(i) ? '---:' : '---'
  );

  const toRow = cells => '| ' + cells.join(' | ') + ' |';
  return [toRow(headers), toRow(separator), ...rows.slice(1).map(toRow)].join('\n');
}

const csv = `商品,单价\n键盘,299\n鼠标,129`;
console.log(csvToMarkdown(csv, [1])); // 第 1 列右对齐

Python

import csv
import io

def csv_to_markdown(csv_text, align_right=None):
    align_right = align_right or []
    reader = csv.reader(io.StringIO(csv_text.strip()))
    rows = [[cell.replace('|', '\\|') for cell in row] for row in reader]

    if not rows:
        return ''

    headers = rows[0]
    col_widths = [max(len(row[i]) for row in rows) for i in range(len(headers))]

    def fmt_row(cells):
        padded = [cells[i].ljust(col_widths[i]) for i in range(len(cells))]
        return '| ' + ' | '.join(padded) + ' |'

    sep = [('-' * w + ':') if i in align_right else '-' * w
           for i, w in enumerate(col_widths)]

    lines = [fmt_row(headers), '| ' + ' | '.join(sep) + ' |']
    lines += [fmt_row(row) for row in rows[1:]]
    return '\n'.join(lines)

csv_text = "商品,单价\n键盘,299\n鼠标,129"
print(csv_to_markdown(csv_text, align_right=[1]))

Markdown 表格的局限

Markdown 表格有些限制需要了解：

  • 不支持合并单元格：没有 colspan 或 rowspan。复杂布局需要用 HTML 表格。
  • 不支持多行单元格：单元格内容必须单行。换行会破坏表格结构。
  • 不支持样式：字体、颜色、边框样式由主题决定，Markdown 本身无法控制。
  • 超宽表格：列数超过 30 或行数超过几百行时，可读性会很差。考虑拆分或用代码块。

遇到 Markdown 满足不了的情况，GitHub 也支持内联 HTML 表格：

<table>
  <tr><th>姓名</th><th>角色</th></tr>
  <tr><td>Alice</td><td>工程师</td></tr>
</table>

在线 CSV 转 Markdown 工具

ZeroTool CSV 转 Markdown 工具 完全在浏览器内运行，粘贴 CSV，选择列对齐方式，复制 Markdown 输出。文件不会上传，不需要注册账号。

打开 CSV 转 Markdown 工具 →