「一键格式化」听起来是最容易做的功能——把文本丢给 Prettier拿回结果替换掉。真做起来有四个坎Prettier 全量加载比整个应用主包还大中文段落不能按 printWidth 折行格式化后光标不能跳到文首CtrlZ必须一步撤销干净不能把用户刚打的字一起吞掉。MarkView https://markview.arthttps://github.com/acheding/markview的实现只有 45 行但每一行背后都有一个决策。一、体积全量 Prettier 比主包还大先看数字。这套方案要用的 Prettier 模块构建产物是这样的chunk原始体积gzipstandalone83 KB27 KBmarkdown270 KB92 KByaml144 KB44 KBbabel320 KB83 KBestree215 KB63 KBpostcss159 KB45 KBhtml163 KB51 KB合计约 1.32 MB约 406 KB而应用主包是 857 KB。全量 Prettier 比整个应用还大。所以懒加载不是优化是前提条件// src/services/formatter.js// Markdown 格式化服务Prettier standalone 及插件全部走动态 import// Vite 拆成独立异步 chunk首次调用「格式化文档」才下载主包体积零增长。// 插件覆盖:markdown 本体、front matter(yaml)、代码块 js/json(babelestree)、css(postcss)、html;// 其余语言(python、mermaid 等)Prettier 不认识,代码块原样保留、不会被破坏。letenginePromisenullconstloadEngine(){if(!enginePromise){enginePromisePromise.all([import(prettier/standalone),import(prettier/plugins/markdown),import(prettier/plugins/yaml),import(prettier/plugins/babel),import(prettier/plugins/estree),import(prettier/plugins/postcss),import(prettier/plugins/html)]).then(([standalone,...plugins])({formatWithCursor:standalone.formatWithCursor,plugins}))// 加载失败如离线时 chunk 拉取失败不缓存 rejected promise下次调用可重试。enginePromise.catch((){enginePromisenull})}returnenginePromise}「失败不缓存 rejected promise」这一句是个容易漏的细节如果直接把失败的 promise 留在缓存里用户离线时点了一次格式化之后整个会话都无法再重试——因为后续每次调用拿到的都是同一个已经 reject 的 promise。插件清单也是取舍的结果。TypeScript 插件被刻意排除了chunk 太大代价换不来收益ts 代码块的现状是原样保留、不被破坏。顺带一个容易忘的改动prettier要从devDependencies移到dependencies——它现在是运行时依赖不再只是构建期工具。二、中文段落proseWrap必须是 preserve调用配置只显式设了三个选项exportconstformatMarkdownasync(text,cursorOffset0){const{formatWithCursor,plugins}awaitloadEngine()constresultawaitformatWithCursor(text,{parser:markdown,plugins,proseWrap:preserve,cursorOffset:Math.max(0,Math.min(Math.trunc(cursorOffset)||0,text.length))})return{formatted:result.formatted,cursorOffset:result.cursorOffset}}proseWrap: preserve是整个方案的关键。它的语义是段落内的换行原样保留既不按 printWidth 重新折行always也不把软换行合并成一行never。为什么中文必须用它因为Prettier 的折行算法按空格断词。中文没有词间空格一整段中文会被当成一个超长的「单词」always模式下要么撑破 printWidth要么在标点处胡乱断开。加上全角字符宽度和 printWidth80 个半角本来就对不上怎么调都是错的。preserve直接绕开了整个问题。测试就是钉死这个行为it(proseWrap preserve超长中文段落不被折行,async(){constparagraph这是一段特意写得很长的中文正文长度远远超过八十个字符的默认打印宽度格式化之后必须保持为完整的一行不能被换行打断。const{formatted}awaitformatMarkdown(# 标题\n\n${paragraph}\n)expect(formatted).toContain(\n${paragraph}\n)})这里还有个容易混淆的点项目根目录有一份.prettierrc.jsontabWidth: 4、semi: false等但它只作用于项目自己的源码。prettier/standalone不读配置文件运行时格式化用户文档走的全是 Prettier 默认值——所以文档里的 JS 代码块会被补上分号尽管项目自身的代码风格是不加分号的。至于实际生效的规则表格按列宽对齐、分隔行归一为| --- |、无序列表符号统一成-、粗体统一**、块级元素之间的空行规范化、front matter 交给 yaml 插件重排。三、代码块内的代码也格式化了——一行代码没写文档里的 JS 代码块也被格式化了const a{x:1,y: 2}变成const a { x: 1, y: 2 };。实现方式是什么都没做。项目里没有一行代码去扫围栏、切片、拼回。这是 Prettier markdown 插件自带的 embedded-language 能力——只要把对应的 parser 插件一起传进plugins数组它就会对code节点走embed拿围栏的 info string推断出 parserjs/jsx→ babeljson→ jsoncss/scss/less→ postcsshtml/vue→ html子格式化后按缩进塞回去。推断不出来的就原样打印。所以 mermaid、python 这些块完全不受影响——测试里用toContain(原文)逐字断言了这一点。因为「语言标记决定了能不能格式化」插入代码块的命令特意把光标停在语言标记位// 插入围栏代码块光标停在语言标记位标记决定高亮与格式化能力如 JSON 内容应标 json 而非 js。用户敲下CtrlAltK光标就在三个反引号后面顺手敲json就行——一个小设计让「标语言」变成了默认动作而不是额外负担。四、光标官方 API 加一次 clampPrettier 有官方方案formatWithCursor(source, { cursorOffset })返回的结果里带一个新的cursorOffset已经是格式化后文本中的偏移。所以不需要自己做锚点映射。项目做的唯一处理是防御性 clampcursorOffset:Math.max(0,Math.min(Math.trunc(cursorOffset)||0,text.length))Math.trunc(...) || 0同时吃掉NaN、undefined和小数再夹进合法区间——传越界的 offset 会让 Prettier 直接抛错。采样端取的是主选区的head而非anchor// 当前光标主选区头部在文档中的绝对偏移供格式化前采样、格式化后映射回位。getCursorOffset:()view.state.selection.main.head,测试用「切片比对」而不是硬编码数字写法值得抄it(光标映射到格式化后的对应位置,async(){constsource* item\n\n| a | b |\n|---|---|\n| 1 | 2 |\n\ntail\nconst{formatted,cursorOffset}awaitformatMarkdown(source,source.indexOf(tail))expect(formatted.slice(cursorOffset,cursorOffset4)).toBe(tail)})fixture 特意在光标前面放了会改变长度的内容*变-、|---|变| --- |所以如果 offset 是原样透传的这条断言必挂。五、撤销一次 CtrlZ不多不少这是全篇最值得记的一个坑而且是端到端验证阶段才抓到的。第一层保证很直觉——整篇替换写成一个事务天然是一个 history eventview.dispatch({changes:{from:0,to:view.state.doc.length,insert:text},// …})但实际测下来会发现格式化之后马上继续打字按一次CtrlZ新打的字连同格式化一起被撤销了。原因是 CodeMirror 的 history 默认有 500ms 的newGroupDelay会把时间接近的事务合并成一个撤销单元。解法是显式隔离// 应用格式化结果整段替换 光标落到映射后的新位置并滚动可见。// 单次 dispatch 单步撤销isolateHistory 阻止本事务与格式化后紧接的输入合并成一步// 否则 500ms 内继续打字会让一次 CtrlZ 连输入带格式化一起回退。applyFormatted(text,anchor){if(textview.state.doc.toString())returnconstpositionMath.max(0,Math.min(Number.isInteger(anchor)?anchor:0,text.length))view.dispatch({changes:{from:0,to:view.state.doc.length,insert:text},selection:{anchor:position},effects:EditorView.scrollIntoView(position,{y:center}),annotations:isolateHistory.of(full)})},isolateHistory.of(full)表示前后都不许合并另有before/after可选。这类 bug 的特点是单测抓不到——它不在纯函数里而在编辑器的时间行为里。只有真的在浏览器里格式化完接着打字、再按 CtrlZ才会暴露。六、异步带来的竞态格式化是异步的首次还要下载 chunk这期间用户可以继续打字、切换文档、甚至再按一次快捷键。四道防线// Ctrl/Cmd Alt F整篇 Prettier 格式化Markdown 结构 受支持语言的代码块// 光标经 formatWithCursor 映射保持原位。格式化是异步的首次还要加载引擎 chunk// 期间用户可能继续输入或切换文档应用前核对文档未变变了则静默放弃、绝不覆盖新输入。letisFormattingfalseconstformatDocumentasync(){consteditoreditorControllerif(!editor||isFormatting)returnisFormattingtruetry{constsourceeditor.getDoc()const{formatted,cursorOffset}awaitformatMarkdown(source,editor.getCursorOffset())if(editorController!editor||editor.getDoc()!source)returnif(formattedsource){toast.show(内容已符合格式)return}editor.applyFormatted(formatted,cursorOffset)toast.show(已格式化CtrlZ 可整体撤销,{tone:success})}catch{toast.show(格式化失败内容未做改动,{tone:error,duration:3000})}finally{isFormattingfalse}}重入锁isFormatting连按快捷键不会并发跑两遍。双重竞态核对既查控制器实例是否被换掉切文档、编辑器重建又查文档内容是否被改过。命中就静默 return——不 toast、不覆盖。用户在等待期间打的字比一次格式化重要。catch 兜底Markdown 或代码块有语法错误时 Prettier 会抛提示「内容未做改动」原文不动。幂等短路已经符合格式时提示「内容已符合格式」而不是「已格式化」避免制造一个什么都没变的撤销步。诚实地说一个缺口没有超时机制。Prettier 是同步 CPU 密集的超大文档理论上会卡住主线程一段时间目前只有重入锁拦住重复触发。七、为什么渲染上了 Worker格式化没有这是同一个项目里的一处有意思的对比。Markdown 渲染做了完整的 Worker 化后台线程渲染、序号防乱序、Worker 崩溃时动态 import 同步版本降级细节见渲染管线篇。而格式化全程跑在主线程async只来自动态 import 和 Prettier 3 的 promise API不是并发。判断依据是频率渲染每次击键都跑一次卡顿就是持续可感的输入延迟格式化是低频的、用户显式触发的一次性操作跑 200ms 用户是有心理预期的。工程上的取舍不该看「这个技术是不是更好」而该看「这个代价是不是值得」。如果哪天要给格式化做 Worker 化现成的渲染调度器就是可复用的范式——但在此之前多一层线程通信就是多一层可能出错的地方。结语三条经验懒加载的边界要看清——当依赖比主包还大时「首次使用才下载」不是优化选项而是可行性前提同时记得让失败的加载可重试。国际化的坑常常藏在算法假设里——proseWrap的问题本质不是配置选错而是 Prettier 的折行算法假设了「词由空格分隔」中文不满足这个前提。有些 bug 只有真机能抓——撤销栈合并、光标漂移这类问题不在纯函数里单测再全也覆盖不到纯逻辑用 Vitest交互时序留给端到端验证两者不互相替代。
