marked.js 开启 GFM 支持：正确解析表格与任务列表的配置方法

一、marked.js 的 GFM 支持机制与环境准备

marked.js 是前端和 Node.js 生态中广受使用的 Markdown 解析器。早期的 Markdown 规范（CommonMark）侧重于基础段落、标题、粗斜体、引用和普通列表，并不包含数据表格和任务复选框语法。GitHub 基于自身协同需求推出了 GFM 规范，定义了由管道符 | 与连字符 - 构成的二维表格，以及形如 - [ ] 和 - [x] 的任务清单。

在 marked.js 的现代架构（v4.x 至最新版）中，解析机制被拆分为 Lexer（词法切分）、Tokenizer（标记提取） 与 Renderer（HTML 渲染器） 三层。GFM 选项在词法分析阶段作为主干开关：开启时，分词器会主动匹配表格模式与任务列表前缀并将其转换为专属 Token 对象；若此开关被关闭或配置失真，表格将退化为单行文本，任务列表的方括号也会被当做普通字符直接输出。

1. 安装与项目引入

在 Node.js 或支持模块化打包的前端工程中，推荐通过 npm 安装 marked，并协同安装 DOM 安全净化工具 dompurify（浏览器环境）或 isomorphic-dompurify（通用环境）：

# 在项目根目录下执行安装命令
npm install marked dompurify

在 ES 模块规范中完成基础导入：

import { marked } from 'marked';
import DOMPurify from 'dompurify';

若在纯静态 HTML 页面中通过 CDN 引入，则可使用对应的 UMD 脚本标签：

<!-- 引入 marked 与 DOMPurify CDN -->
<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dompurify/dist/purify.min.js"></script>

二、开启 GFM 支持的核心配置与代码实现

虽然在部分 marked.js 默认构建中 gfm 为 true，但在大型项目或包含多重插件配置的场景中，强烈建议通过官方推荐的 marked.use() 组合式 API 进行显式声明。这能防止其他中间件或遗留的 setOptions 将配置意外重置。

1. 核心选项声明

配置时涉及的主要选项包括 gfm、breaks 和 pedantic：

• gfm: true：必须设为 true，激活 GFM 规范中的表格、任务列表、删除线等语法特性。
• breaks: false：控制单个换行符是否渲染为 <br>，解析表格时建议保持 false，遵循标准段落规范。
• pedantic: false：必须保持为 false。若开启 pedantic（严格兼容原有 Markdown.pl 规范），解析器会完全屏蔽 GFM 扩展，导致表格与任务列表失效。

// 显式声明 GFM 基础配置
marked.use({
  gfm: true,
  breaks: false,
  pedantic: false
});

2. 任务列表与渲染器定制

默认情况下，marked.js 对任务列表解析生成的复选框带有 disabled="" 属性。这在只读文档展示场景是合理的，但在富文本待办清单或需要前端响应勾选的应用中，需要扩展 renderer.listitem 来自定义输出结构：

// 定制 Renderer 增强任务列表
marked.use({
  renderer: {
    listitem(token) {
      // 当 Token 具有 task 标记时，自定义渲染结构
      if (token.task) {
        const isChecked = token.checked ? 'checked' : '';
        return `<li class="task-list-item" style="list-style-type: none; display: flex; align-items: center; gap: 6px;">
          <input type="checkbox" ${isChecked} class="task-checkbox" aria-label="待办任务项">
          <span>${token.text}</span>
        </li>\n`;
      }
      // 普通列表保持默认项
      return `<li>${token.text}</li>\n`;
    }
  }
});

3. 完整的解析与挂载示例

以下是在现代浏览器环境中从 Markdown 源码解析、经过安全净化并挂载至页面的完整端到端代码：

import { marked } from 'marked';
import DOMPurify from 'dompurify';

// 1. 声明待解析的 Markdown 文本
const markdownSource = `
### 系统模块排查表

| 功能模块 | 解析引擎 | 状态 | 优先级 |
| :------- | :------: | :--- | -----: |
| 数据表格 | GFM Table | 正常 | 1 |
| 任务列表 | GFM Task  | 就绪 | 2 |

### 阶段验收目标

- [x] 完成 marked.js 显式 GFM 选项声明
- [x] 验证表头分隔线对齐属性
- [ ] 完成跨浏览器视觉样式与无障碍适配
`;

// 2. 配置 marked 启用 GFM
marked.use({
  gfm: true,
  pedantic: false
});

// 3. 执行语法解析
const rawHtml = marked.parse(markdownSource);

// 4. 安全净化：务必允许 input 标签和相关属性
const cleanHtml = DOMPurify.sanitize(rawHtml, {
  ADD_TAGS: ['input'],
  ADD_ATTR: ['type', 'checked', 'disabled', 'aria-label']
});

// 5. 挂载到宿主容器
document.getElementById('content-root').innerHTML = cleanHtml;

三、表格与任务列表的源码语法规范要求

很多开发者在配置了 gfm: true 后依然遇到“表格不解析”或“复选框原样显示为文字”的现象，其根源往往不在于 marked 库的配置，而在于输入的 Markdown 源码违反了 GFM 的语法约束条件。

1. GFM 表格语法约束

• 首尾空行隔离：表格必须与前文段落保持至少一个空行间隔。若紧贴上文文本，词法分析器会将表格行视为普通段落的文本延续。
• 强制分隔行存在：表格由表头（第一行）、分隔行（第二行）和数据行（后续行）组成。分隔行必须包含由连字符构成的线段，例如 | --- | :---: | ---: |，至少包含一个短横线。
• 对齐修饰符：分隔行中的冒号用于指定列对齐方式：:--- 表示左对齐，:---: 表示居中对齐，---: 表示右对齐。marked 会据此为 <th> 和 <td> 生成对应的 align 属性或 CSS 样式。
• 管道符转义：如果单元格内容中本身包含管道字符，必须使用反斜杠进行转义（例如 \|），否则会导致分词器错误识别列边界。

2. GFM 任务列表语法约束

• 标准前缀声明：任务列表必须基于无序列表（-、*、+）或有序列表（1.）构建。列表符号与方括号之间必须存在一个半角空格。
• 半角空格与标记字符：方括号内未完成状态必须严格为一个半角空格 [ ]，已完成状态为小写 [x] 或大写 [X]。使用全角空格或中文字符将导致正则匹配失败。
• 后缀空格隔离：方括号后必须跟至少一个半角空格，紧接着才是具体的任务文本描述，例如 - [ ] 编写测试用例。

四、渲染输出结果验证与安全集成

验证 marked.js 是否正确解析，可以通过比对实际生成的 HTML 节点结构进行检验。

<!-- 表格生成的 HTML 结构示例 -->
<table>
  <thead>
    <tr>
      <th align="left">功能模块</th>
      <th align="center">解析引擎</th>
      <th align="right">优先级</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td align="left">数据表格</td>
      <td align="center">GFM Table</td>
      <td align="right">1</td>
    </tr>
  </tbody>
</table>

<!-- 任务列表生成的 HTML 结构示例 -->
<ul>
  <li><input checked="" disabled="" type="checkbox"> 完成 marked.js 显式 GFM 选项声明</li>
  <li><input disabled="" type="checkbox"> 完成跨浏览器视觉样式与无障碍适配</li>
</ul>

页面视觉样式补全

由于原生浏览器对 <table> 默认不附加边框，且无序列表自带黑圆点标记，为了实现美观的展示效果，通常需要在前端样式表中补充以下基础 CSS：

/* 表格基础边框与折叠样式 */
table {
  width: 100%;
  border-collapse: collapse;
  margin: 1.2em 0;
}
th, td {
  border: 1px solid #D8CFBC;
  padding: 8px 14px;
}
th {
  background-color: #FAF7F1;
  font-weight: 600;
}

/* 任务列表消除前导圆点并对齐复选框 */
li:has(> input[type="checkbox"]) {
  list-style-type: none;
  margin-left: -1.2em;
  display: flex;
  align-items: center;
  gap: 8px;
}

五、常见解析故障排查清单

在实施 GFM 解析时，若遇到非预期结果，可以依据以下核查维度快速排查定位。