markdownlint插件默认启用全部基础规则，导致新建markdown文件即现绿波浪线；需在项目根目录配置.markdownlint.json精准控制规则，如设"md041": false关闭首标题强制要求，并优先保留md013、md029等影响渲染与协作的关键规则。
markdownlint 插件默认开箱即用，但不配规则等于白装——它会用一套宽松的通用规则报一堆你根本不想改的警告。
为什么刚装完 markdownlint 就满屏绿波浪线
因为插件默认启用 markdownlint 库的全部基础规则（比如 MD041 要求首行必须是 #，MD007 强制列表缩进为 2 空格），而多数人写 README 或笔记时根本不会严格遵守这些。
- 常见错误现象：新建
note.md，第一行写 “今天学了 Git”，立刻被标红提示 “Missing first header” - 真实使用场景：个人笔记、团队 Wiki、API 文档草稿，都不需要强制首标题或固定缩进
- 参数差异：规则
MD041默认true，但设为false后就不再检查首行是否为标题 - 性能影响：规则校验在后台异步进行，禁用几条规则几乎无感知；但开启全部规则 + 大文件（>500 行）可能轻微拖慢保存响应
如何用 .markdownlint.json 精准控制规则
项目级配置比用户级设置更可靠——它能随 Git 提交，确保所有协作者看到一致的提示。
- 在项目根目录新建文件：
.markdownlint.json - 写入最小可用配置，例如关闭易冲突项：
{ "default": true, "MD041": false, "MD024": false, "MD007": { "indent": 2 } } -
MD024关闭同级标题重复警告（避免 “## API ## API” 被误报） -
MD007保留列表缩进检查，但允许 2 空格（适配 GitHub 渲染习惯） - 不要在用户 settings.json 里硬写
markdownlint.config，否则容易被工作区设置覆盖
哪些规则建议保留，哪些可以直接关
不是所有警告都值得修。有些规则对可读性有实质帮助，有些只是风格洁癖。
- 建议保留：
MD013（行长度限制）、MD029（有序列表序号连续）、MD033（禁止内联 HTML）——它们直接影响渲染兼容性和协作效率 - 建议关闭：
MD041（首行标题）、MD022（段前空行）、MD004（无序列表符号统一）——除非你在写开源项目规范文档 - 注意陷阱：
MD036（强调文字单独成行）看似合理，但会误杀斜体标题（如*Deployment*），建议设为{"emphasis": false}而非直接false
鼠标悬停看不到规则说明？检查插件状态
有时绿波浪线存在，但悬停无提示，大概率是插件没真正激活或文件类型识别失败。
- 确认当前文件右下角显示 “Markdown”，而不是 “Plain Text” —— 若是后者，点击切换语言模式为
Markdown - 按
Ctrl+Shift+P输入 “Developer: Toggle Developer Tools”，看 Console 是否报markdownlint初始化错误 - 检查 VS Code 设置中是否禁用了扩展：打开
Extensions视图，搜索DavidAnson.vscode-markdownlint，确认状态为 “Enabled” - 极少数情况需重载窗口：按
Ctrl+Shift+P→ 输入 “Developer: Reload Window”
真正难的不是配规则，而是判断哪条规则在当前项目里“算 bug”还是“算风格”。比如 MD003（标题样式）在内部文档里可以放任 atx 或 setext 混用，但在对外 SDK 文档中就必须统一为 atx_closed —— 这个决策没法自动化，得人来定。
