Ruff插件在VSCode中未生效的解决方法包括：一、验证并安装/升级Ruff CLI；二、在VSCode中选择Ruff为Python Linter；三、设置Ruff为默认Formatter并启用保存时格式化；四、手动配置ruffPath路径；五、检查pyproject.toml配置有效性。
如果您在VSCode中使用Ruff插件进行Python代码检查与格式化，但发现其未生效、报错不显示或保存时不自动格式化，则可能是由于插件配置缺失、Python解释器未正确识别或Ruff可执行文件路径未设置。以下是解决此问题的步骤：
本文运行环境：MacBook Air，macOS Sequoia。
一、验证Ruff CLI是否已全局安装
Ruff插件依赖本地Ruff命令行工具，若未安装或版本过低，插件将无法调用核心功能。需确保终端中可直接执行ruff命令。
1、打开终端，输入 ruff --version 并回车。
立即学习“Python免费学习笔记（深入）”；
2、若提示 command not found: ruff，则需通过pipx安装：执行 pipx install ruff。
3、若已安装但版本低于0.5.0，执行 pipx upgrade ruff 更新至最新稳定版。
二、配置VSCode启用Ruff作为默认Linter
VSCode需明确指定Ruff为Python语言的活动Linter，否则即使插件已启用，也不会触发语法检查。
1、按下 Cmd + Shift + P（Mac）或 Ctrl + Shift + P（Windows/Linux），打开命令面板。
2、输入并选择 Python: Select Linter。
3、在弹出列表中选择 Ruff，确认启用。
三、设置Ruff Formatter为默认格式化工具
仅启用Linter不足以实现保存时自动格式化，必须将Ruff注册为Python文件的默认Formatter，并禁用与其他格式化器（如autopep8、black）的冲突。
1、进入VSCode设置（Cmd + ,），搜索 python.formatting.provider。
2、点击下拉菜单，选择 ruff。
3、搜索 editor.formatOnSave，确保其值为 true。
4、搜索 python.formatting.ruffArgs，点击“编辑设置（JSON）”，添加如下项："python.formatting.ruffArgs": ["--fix"]。
四、手动指定Ruff可执行路径（适用于非标准安装）
当Ruff未安装在系统PATH中（例如通过poetry或venv局部安装），VSCode无法自动定位，需显式声明其绝对路径。
1、在终端中执行 which ruff，复制输出的完整路径（如 /Users/xxx/.local/bin/ruff）。
2、进入VSCode设置，搜索 python.linting.ruffPath。
3、点击“编辑设置（JSON）”，添加键值对："python.linting.ruffPath": "/Users/xxx/.local/bin/ruff"。
五、检查工作区级pyproject.toml配置有效性
Ruff行为高度依赖项目根目录下的 pyproject.toml 文件。若该文件缺失、语法错误或未启用所需规则，插件将降级为默认配置。
1、在项目根目录新建或编辑 pyproject.toml。
2、确保包含至少以下最小配置段：[tool.ruff] 与 [tool.ruff.lint]。
3、在 [tool.ruff.lint] 下添加 select = ["E", "F", "I"] 以启用常见错误与风格检查。
4、保存文件后，重启VSCode窗口使配置重载。
