必须手动指定editor.defaultFormatter为charliermarsh.ruff，否则VSCode会fallback到其他格式化器；需确认Ruff CLI已安装且路径正确，配置Python专属settings.json中"[python]"块，启用formatOnSave和codeActionsOnSave的fixAll与organizeImports，并验证ruff.toml和Python解释器是否匹配。
必须手动指定 editor.defaultFormatter 为 charliermarsh.ruff，否则即使 Ruff 扩展已安装、CLI 可运行，VSCode 仍会 fallback 到其他格式化器（如 autopep8 或 black），导致保存时不生效。
确认 Ruff CLI 已就绪且路径正确
Ruff 扩展不自带二进制，完全依赖系统 PATH 中的 ruff 命令。VSCode 图形界面和内嵌终端需能一致识别它。
- 在系统终端执行
ruff --version，确认输出类似ruff 0.7.2 - 若 VSCode 内嵌终端报
command not found: ruff，重启 VSCode；仍失败则需手动配置路径 - 打开 VSCode 设置，搜索
ruff.path，填入绝对路径，例如：/opt/homebrew/bin/ruff（macOS Homebrew）或/Users/xxx/Library/Python/3.12/bin/ruff（pip 用户） - 不要用
~符号，必须是完整路径；Windows 用户注意反斜杠要写成C:\Users\xxx\AppData\Roaming\Python\Scripts\ruff.exe
设置 Python 语言专属的默认格式化器
VSCode 的格式化行为按语言 ID 绑定，[python] 块配置不可省略，也不能写成全局 editor.defaultFormatter。
- 打开命令面板（
Cmd+Shift+P或Ctrl+Shift+P），输入并选择Preferences: Open Workspace Settings (JSON)（推荐优先配工作区） - 在
settings.json中添加如下块（不是覆盖整个文件）：
{
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true
}
}
- 确保没有其他插件（如
ms-python.black-formatter）同时启用；若有，禁用或卸载，避免冲突 - 保存后，在任意
.py文件中按Shift+Alt+F测试是否触发格式化（观察状态栏是否短暂显示 “Formatting with Ruff”）
启用保存时自动修复与导入整理
仅格式化不够，Ruff 还能自动修复 lint 错误、排序 import —— 这些需通过 codeActionsOnSave 显式开启，且必须限定为 ruff 提供的动作。
立即学习“Python免费学习笔记（深入）”；
- 在同个
settings.json的[python]块内补全配置：
{
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.ruff": true,
"source.organizeImports.ruff": true
}
}
}
-
source.fixAll.ruff仅作用于 Ruff 报出的可修复项（如F401 unused import），不会动 ESLint 或 Pylance 的问题 -
source.organizeImports.ruff依赖ruff.toml中启用了isort规则（即extend-select = ["I"]），否则无效果 - 不要写成
"source.fixAll": true—— 它会尝试调用所有可用 Linter，容易报错或静默失败
验证配置是否真正生效
最常被忽略的是：Ruff 配置文件未被读取，或 Python 解释器选错，导致看似配置完成，实则“假就绪”。
- 在项目根目录放一个
ruff.toml，至少含基础规则：select = ["E", "F", "I"]和line-length = 88 - 打开命令面板，执行
Python: Select Interpreter，确认右下角状态栏显示的是你项目虚拟环境里的python（如./venv/bin/python），不是系统 Python - 修改一个
.py文件，故意写长行或多余 import，保存后观察：- 错误波浪线是否来自 Ruff（悬停看提示含
ruff:）？ - 多余 import 是否被删掉？长行是否被折行？
- 错误波浪线是否来自 Ruff（悬停看提示含
- 如果没反应，打开 VSCode 输出面板（
Ctrl+Shift+U），选择Ruff Server，看是否有Failed to start或路径错误日志
真正的卡点往往不在扩展安装，而在 CLI 路径、Python 解释器、配置文件位置三者是否对齐 —— 少一个，Ruff 就只是个图标。
