必须安装davidanson.vscode-markdownlint插件，卸载所有含cli/command字样的干扰插件；配置文件需置于工作区根目录且为合法json；自动修复需开启autofixonsave并禁用prettier冲突。
怎么确认装的是对的插件
VSCode 里搜 markdownlint，出来一堆名字相近的扩展，但真正提供编辑器内实时标红、悬停提示、保存修复能力的，只有 DavidAnson.vscode-markdownlint。其他像 markdownlint-cli2 或 markdownlint-command 是命令行封装工具，不参与编辑器内校验。
打开 Extensions 面板（Ctrl+Shift+X），搜 markdownlint，只保留发布者是 David Anson 的那个，卸载所有带 cli、command、vscode-markdownlint-prettier 字样的插件——它们会干扰规则加载和修复行为。
装完重启 VSCode，打开一个 .md 文件，手动写一行 ## 标题 （末尾多一个空格），如果立刻出现绿色波浪线并提示 MD024/no-duplicate-heading 类错误，说明插件已生效。
.markdownlint.json 放哪儿才管用
VSCode 的 vscode-markdownlint 插件只认当前工作区根目录下的 .markdownlint.json（或 .markdownlint.yaml），不会向上递归查找父文件夹，也不会读取用户全局设置里的 markdownlint.config —— 只要项目根目录存在本地配置文件，它就直接忽略你 settings.json 里写的任何 markdownlint.config。
确保你用的是 File > Open Folder 打开整个项目文件夹，而不是单个 .md 文件；然后把 .markdownlint.json 放在这个打开的文件夹最顶层。
- 配置必须是合法 JSON：双引号、无末尾逗号、不能有注释（
//或/* */都非法） - 规则 ID 大小写敏感：
MD013有效，md013或MD13会被静默忽略 - 想临时跳过某条规则？在文件顶部加
<!-- markdownlint-disable MD013 -->，比改配置更快更安全
哪些规则能自动修复，哪些不能
不是所有规则都支持保存时自动修正。MD013/line-length、MD007/ul-indent、MD029/ol-prefix 这些目前官方标记为不可修复（fixable: false），开了 autoFixOnSave 也白搭。
能修的规则，比如 MD003/headings（标题风格）、MD004/ul-style（列表符号）、MD026/no-trailing-punctuation（结尾标点），必须配合正确配置才能触发：
-
"markdownlint.autoFixOnSave": true（必须显式开启） -
"editor.formatOnSave": true（格式化流程需启用） - 当前文件语言模式是
markdown（右下角状态栏点一下确认，别是plaintext） - 禁用 Prettier 的
formatOnSave，否则它会在 markdownlint 修复后立刻重写，造成“修了又变回去”
验证方式：删掉 prettier 插件，保存一次，看修复是否稳定生效。
团队共用规则时最容易漏掉的细节
团队文档规范落地最难的不是写规则，而是让所有人用同一套配置且不被覆盖。常见断点：
- 有人在自己用户 settings.json 里写了
markdownlint.config，但项目根目录有.markdownlint.json，结果他本地生效、别人不生效 - 规则里用了自定义正则（如
"MD999": { "names": ["/^TODO:/"] }），这类规则一律不可修复，且容易因语法错误导致整个配置加载失败 - 误把
prettier-plugin-markdown当成 markdownlint 替代品——它是格式化器，不提供 lint 提示，也不能关规则、调参数
建议团队统一提交 .markdownlint.json 到仓库根目录，并在 README 里注明「此配置不可绕过」，避免个人设置覆盖协作基准。
