6.2 常见插件配置项解析

6.2 常见插件配置项解析

本节摘要：格式化、代码检查、语言服务三类装备的配置项是配置治理的主战场。本节逐类给出规范写法：格式化器的按语言指派与配置文件优先、检查器的作用域与工作目录、语言服务的引擎版本与项目绑定；末尾给出配置漂移的止血方案。规范写法不是风格洁癖，是直接决定装备打不打架的工程问题。

领地宪法立好了（上一节的五层金字塔），这一节按宪法把三类主力装备的配置逐类过手。之所以选这三类：它们是前几轮升级里配置面最宽、也最容易互相干扰的装备——格式化器管改写你的代码，检查器管评判你的代码，语言服务管理解你的代码，三者配置一乱，编辑器的行为立刻不可预测。

格式化器：指派唯一，真相源在项目

格式化配置的第一纪律：每个语言一个默认格式化器，指派唯一。多格式化器并存而未指派时，保存动作不知道该请谁，编辑器要么报"多个格式化器"的错，要么静默选用非预期的一个。规范写法：

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  },
  "[html]": {
    "editor.defaultFormatter": "vscode.html-language-features"
  }
}
​

语言块里的指派显式写全（哪怕与全局默认相同），意图一目了然，后来者读配置不用推理。第二纪律：排版参数的真相源在项目的格式化配置文件，编辑器侧只做指派与触发，不重复抄参数——同一份缩进宽度写在两处，迟早改了一处忘另一处，排版行为随"哪处 newer"漂移。

代码检查器：作用域收敛与工作目录

检查器配置的坑比格式化器深，因为它多一个维度：在哪些文件上跑、以哪里为根跑。规范写法三件套：

{
  "eslint.workingDirectories": [
    { "pattern": "apps/*" },
    { "pattern": "packages/*" }
  ],
  "eslint.validate": [
    "javascript",
    "typescript",
    "javascriptreact",
    "typescriptreact"
  ],
  "eslint.useFlatConfig": true
}
​

工作目录标明 monorepo 的各子包根，检查器才能找对每包的规则文件（不标时的典型症状：子包规则失效、报"找不到规则文件"）；校验语言清单显式列出，避免新文件类型默默漏检；新式配置格式开关跟随项目实际采用的格式版本。规则本身仍然进项目（第 2 章的原则），编辑器侧这些是"怎么把规则跑起来"的接线配置，随工作区入库。

语言服务：版本绑定项目

语言服务的配置核心是一个意识：分析引擎的版本应该由项目说了算。编辑器内置一份引擎，项目依赖里往往也有一份，两份的版本差会造成"编辑器报错与命令行构建不一致"的灵异现象。规范解法（第 3 章埋过伏笔，这里正式立法）：

{
  "typescript.tsdk": "node_modules/typescript/lib",
  "java.import.gradle.enabled": true,
  "python.languageServer": "Pylance",
  "gopls": { "buildFlags": [], "formatting.gofumpt": true }
}
​

引擎目录指向项目自带的版本，语言服务的诊断口径与项目构建一致；各语言服务自身的深度参数（如 Go 语言服务的格式化变体）按项目微调。这类配置全部落工作区级——它们描述的是"项目的分析口径"，天然属于项目领地。

配置漂移的止血

配置不是写完就完了，它会漂：装备升级带来设置键废弃（第 4 章 Python 检查器换代就是一例）、项目迁移留下孤儿键、复制粘贴带进不相干的键。止血三步：定期看废弃提示——设置页里划线的键与启动时的迁移通知，出现一批清一批；每季度做一次"已修改"盘点——设置页能筛出相对默认值动过的所有键，逐键自问"这个还成立吗、该在哪层"；工作区设置进评审——它既然入库，就像代码一样评审着改，防止它从"项目宪法"退化成"个人草稿本"。

台面实测：一间配置混乱工位的治理

实测全流程。症状：某 monorepo 项目，保存格式化时好时坏、检查时灵时不灵。诊断：格式化器指派写在用户级且只覆盖部分语言；检查器工作目录未标；语言服务用内置引擎而项目用旧版。治理：把三类配置按上面的规范写法重写进工作区设置（指派全、目录标、引擎绑），用户级清掉越界键，入库走评审。验证：三台机器拉取后行为一致，保存管线（2.2 节）复跑稳定。整个治理不到半小时，但每一步都建立在分层与规范之上——这就是"联调"的含金量。

坑点提醒

坑一，语言块写错键名。 语言块里的键生效条件严格，块外抄进来的键无效且无提示；写完实测一次保存动作验证。坑二，检查器静默失效。 配置文件路径或格式版本不对时检查器不报"我坏了"，只是不再标问题——"突然不报错"与"突然报错"一样值得警惕。坑三，参数双写。 编辑器侧抄了一份项目参数（行宽之类），两处必漂；编辑器侧永远只留指派与触发。

常见疑问快答

问：怎么快速知道某条设置到底“写在哪层、被谁覆盖”？答：设置界面里搜到该项，右侧会标注当前生效值与来源层；或开 JSON 视图看合并结果。排查配置问题的第一步永远是“确认生效值”，而不是急着改——改错层是最常见的返工原因。

问：装备升级后旧设置键废弃，不理它会怎样？答：短期内多数只是不再生效（静默失效），但部分废弃键会触发启动迁移提示、极少数会与新键冲突产生未定义行为。正确姿势是照迁移提示走完，把旧键清场——这既是卫生问题，也是给接手者留的德行。

替代方案

配置治理没有"替代方案"——它是内置机制的纪律问题，只有"做与不做"。偷懒的代价前面反复出现过：行为漂移、团队不同脸、灵异问题消耗排查时间。下一节处理更硬核的战场：装备已经打架了、工位已经卡了，怎么断案。