Ruff在VSCode中未正常工作需依次检查扩展安装、CLI配置、规则文件、格式化设置及语言服务器状态。确保安装官方Ruff扩展并重启，通过pip或Homebrew安装ruff CLI并配置正确路径，创建ruff.toml启用规则，设置python.formatProvider为ruff且开启format on save，最后重启Ruff服务器并验证Python解释器与CLI版本。
如果您在VSCode中使用Ruff作为Python代码检查与格式化工具，但发现其未按预期工作或功能缺失，则可能是由于扩展未正确安装、配置未生效或语言服务器未启动。以下是解决此问题的步骤：
本文运行环境：MacBook Air，macOS Sequoia。
一、安装Ruff扩展并启用
Ruff需要通过VSCode官方扩展市场中的“Ruff”扩展来提供语法高亮、实时诊断和快速修复支持。该扩展依赖本地Ruff二进制文件执行分析，因此必须同时满足扩展安装与CLI可用两个条件。
1、打开VSCode，点击左侧活动栏的扩展图标（或按快捷键Ctrl+Shift+X）。
立即学习“Python免费学习笔记（深入）”；
2、在搜索框中输入Ruff，找到由charliermarsh发布的官方扩展，确认发布者为verified publisher。
3、点击“安装”，安装完成后点击“重新加载”按钮使扩展生效。
二、安装Ruff CLI并配置路径
Ruff扩展本身不内置可执行文件，必须在系统PATH中提供ruff命令，否则将提示“Ruff not found”。可通过pip、Homebrew或直接下载二进制方式安装，确保VSCode终端与图形界面均能识别该命令。
1、在终端中运行命令：pip install ruff，等待安装完成。
2、验证安装：执行ruff --version，输出类似ruff 0.6.4即表示成功。
3、若VSCode内嵌终端无法识别ruff，重启VSCode；若仍无效，在VSCode设置中搜索ruff.path，手动设置为完整路径，例如/opt/homebrew/bin/ruff（macOS Homebrew默认路径）或/Users/username/Library/Python/3.12/bin/ruff（pip用户安装路径）。
三、配置Ruff规则与格式化行为
VSCode的Ruff扩展默认读取项目根目录下的ruff.toml或pyproject.toml中[ruff]段落的配置。若未配置，将启用Ruff默认规则集，可能忽略部分常用检查项或自动修正行为。
1、在项目根目录创建ruff.toml文件。
2、写入基础配置，例如启用所有安全规则并允许自动修复：
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
select = ["ALL"]
extend-select = ["I"]
fixable = ["ALL"]
3、保存文件后，VSCode将自动重新加载配置，编辑器底部状态栏应显示Ruff: Ready。
四、启用保存时自动格式化
要使Ruff在保存.py文件时自动应用格式化（等效于ruff format），需在VSCode中显式启用格式化提供程序并绑定到Python语言模式。该设置独立于通用“format on save”，必须指定Ruff为首选格式化工具。
1、按下Cmd+, 打开设置，搜索python format provider，将其值设为ruff。
2、继续搜索format on save，勾选该项。
3、再搜索default formatter，点击“在settings.json中编辑”，添加如下行：
"[python]": {"editor.defaultFormatter": "charliermarsh.ruff-vscode"}
五、排查语言服务器未响应问题
Ruff扩展基于LSP（Language Server Protocol）运行，若出现“diagnostics not showing”或“no quick fixes available”，常因语言服务器进程崩溃、Python解释器路径错误或ruff CLI版本过旧导致。
1、在VSCode命令面板（Cmd+Shift+P）中输入并选择Ruff: Restart Server。
2、检查Python解释器是否已选定：点击VSCode窗口右下角Python版本标识，选择一个含site-packages的解释器路径（如/usr/local/bin/python3）。
3、在终端中运行ruff check --preview test.py --show-source，确认CLI可正常输出诊断结果；若报错，升级Ruff至最新版：pip install -U ruff。
