fuxi-fmt

面向中文技术写作的 Markdown 格式化工具。

亮点

• 一个工具同时管块级结构与中文排版。 空行、标记空格、有序列表重编号、列表缩进、中英之间加空格、中文标点全角或半角、行内代码两侧的空格，全部由同一套配置决定，all in one。
• 不该改的不动。 代码块内容、行内代码与公式、HTML 块与注释、MDX/JSX、shortcode、wikilink、URL 与链接目标全部逐字节保持原样；TOML front matter 同样原样保留。
• 拒绝改坏，而且再跑一次不动。 结果与原文的解析树不一致时拒绝写入；解析不得不猜的地方（未终止的围栏、front matter、HTML 注释、公式块）也会拒绝并点名那一行。幂等保证第二次运行不改动任何东西，保存时只产生很小的编辑范围，不打乱光标与撤销历史。
• 几乎所有东西都能在设置里改。 每一个选项都是 VS Code 设置，带默认值、可选值以及它实现的是哪条规范规则，所以设置面板本身就是说明书。

效果示例

同一段文本，格式化前与格式化后：

格式化前：

#安装
他说"试试这个",然后打开了vscode。
- 第一项
- 第二项
| 需求 | fuxi-fmt |
| --- | --- |
| 中英文之间加空格 | 有 |

格式化后：

# 安装

他说“试试这个”，然后打开了 vscode。

- 第一项
- 第二项

| 需求             | fuxi-fmt |
| ---------------- | -------- |
| 中英文之间加空格 | 有       |

表格那一列的宽度按显示宽度算：一个汉字记两格（也推荐安装并使用汉字记两格的等宽字体如 Maple Mono NF CN）。你的字体如果不是这个比例（很多等宽字体里汉字约为拉丁字符的 1.6–1.7 倍），可以在设置里把 table.cjkWidth 调到 1 到 2 之间的任意值。

与主流工具对比

所有判断都来自 先例报告 中逐条链接的第一手文档或源码，数据截至 2026-10。

功能对比

Y = 覆盖，P = 部分或带条件，N = 不覆盖。

可配置项对比

安装

在应用市场搜索 fuxi-fmt，或：

code --install-extension Fux-i.fuxi-fmt-vscode

从源码打包本地 vsix（需要 Node.js >= 22.18，推荐 24 LTS）：

npm ci
npm run vsix
code --install-extension output/fuxi-fmt-<version>.vsix

配置

每个选项都是一个设置。打开设置搜索 fuxiFmt —— fuxiFmt.typography.cjkSpacing、fuxiFmt.list.unorderedMarker、fuxiFmt.blankLines.aroundBlocks 等等。每项都会显示默认值、可选值，以及它实现的是哪条规则，所以设置面板本身就是说明书。

优先级如下，后者覆盖前者：

第 3 层故意压过第 2 层。 命令行与 CI 永远看不到编辑器设置；如果它们优先，编辑器与命令行（--check，用法见 贡献指南）会对同一份文档给出不同结论 —— 保存时通过，流水线里失败。确实想覆盖项目配置时，用第 4 层的 fuxiFmt.config。

{
  "fuxiFmt.enable": true,
  "fuxiFmt.typography.punctuationChangeList": [",", ".", ":", "!", "?", ";"],
  "fuxiFmt.config": { "blankLines": { "aroundBlocks": "atLeast" } }
}

把 fuxiFmt.enable 设为 false，可以关闭使用其格式化。

文档

• 功能规范 —— 行为契约，规则 ID 的权威来源
• 变更日志
• 先例报告 —— 其它工具逐项的选项与出处
• 贡献指南
• 问题反馈

许可证

MIT。见 LICENSE。