必须安装官方Dart Code插件并重启VSCode，确保状态栏显示Dart标识；启用editor.formatOnSave且设置editor.defaultFormatter为Dart-Code.dart-code；格式化由SDK的dartfmt执行，不可自定义规则。

装 Dart 插件是前提，但光装不够

VSCode 默认不带 Dart 支持，必须装官方 Dart Code 插件（作者是 Dart 团队）。别用名字相近的其他插件，比如 Flutter 单独插件或旧版 Dart（已弃用）。装完要重启 VSCode，否则 formatOnSave 可能不生效。

• 插件市场搜 “Dart Code”，认准 publisher 是 Dart-Code.dart-code
• 装完检查状态栏右下角有没有 Dart 或 Flutter 标识，没有说明没激活
• 如果打开 .dart 文件后右键没“Format Document”选项，基本就是插件没正常加载

保存时自动格式化得靠两个配置联动

editor.formatOnSave 控制是否在保存时触发格式化，但它只是开关；真正起作用的是 editor.defaultFormatter 是否指向 Dart 插件的 formatter。两者缺一不可。

• 在设置里搜 formatOnSave，勾选它（全局或工作区均可）
• 再搜 defaultFormatter，找到 Editor: Default Formatter，点击下拉，选 Dart-Code.dart-code
• 如果项目根目录有 .vscode/settings.json，确认里面没写死别的 formatter，比如 "editor.defaultFormatter": "esbenp.prettier-vscode" 会覆盖 Dart

格式化行为由 dartfmt 决定，不是 VSCode 自己排的

VSCode 的 Dart 插件调用的是 SDK 自带的 dartfmt 命令行工具，所以格式效果和你在终端运行 dart format . 完全一致。这意味着：

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 不支持自定义缩进空格数、括号换行风格等——dartfmt 是 opinionated，没配置项
• 如果格式化结果不符合预期（比如某行被强行拆成多行），不是 VSCode 设置问题，而是 dartfmt 规则如此
• 确保 SDK 路径正确：插件需要读取 dart 命令，如果 which dart 返回空，或 dart --version 报错，格式化会静默失败

常见失效场景和快速排查路径

最常遇到的是“点了保存，但代码没变”——大概率不是插件坏了，而是下面某个条件不满足：

• dart 命令不可用：打开 VSCode 内置终端，运行 dart --version，无输出就去配置 dart.sdkPath
• 文件没被识别为 Dart：检查文件后缀是不是 .dart，且状态栏右下角语言模式显示的是 Dart（点它可手动切换）
• 设置了 editor.formatOnSaveMode 为 modifications：这个模式只格式化编辑过的行，容易误以为没生效，建议保持默认 file
• 项目里存在 analysis_options.yaml 且写了 exclude: 匹配了当前文件：格式化也会跳过

Dart 格式化这件事本身很简单，但依赖链比看起来长：VSCode → Dart 插件 → dart CLI → dartfmt。任一环节断掉，都会表现为“自动排版失灵”，而错误提示往往藏在输出面板的 Dart 或 Debug 标签页里，不点开看不到。