sublimelinter-contrib-ruff不是开箱即用插件，需手动确认ruff命令在sublime内置终端可用、sublimelinter中启用ruff linter、pyproject.toml显式启用i/d/up等规则，否则无任何提示。
SublimeLinter-contrib-ruff 不是开箱即用的插件
装完 SublimeLinter-contrib-ruff 插件后，几乎必然没反应——这不是你操作错了，而是它根本不会自己拉起 ruff 进程。这个插件只是“胶水”，只负责把 SublimeLinter 的事件转发给本地 ruff CLI，不带二进制、不自动安装、不读取项目配置文件（如 pyproject.toml）里的 lint 规则。
常见错误现象：
- 保存 Python 文件后控制台（
Ctrl+`）报command not found: ruff - 右下角状态栏显示
Python，但没有变成Python (Ruff) - 写
import os; os.path这种明显未使用的导入，也不标黄或报F401
必须手动确认三件事：
-
ruff --version能在 Sublime 内置终端里成功执行（不是系统终端，也不是你平时用的 iTerm） - SublimeLinter 设置中已启用
rufflinter（默认是禁用状态） -
pyproject.toml里至少启用了基础规则，比如select = ["E", "F", "W", "I", "D"]
如何让 Sublime 找到并调用 ruff
Sublime Text 图形界面启动时，不加载 shell 的 PATH，尤其 macOS + nvm / Windows + conda / Linux + pipx 环境下，ruff 命令常不可见。
最稳的做法是显式指定路径：
- 打开
Preferences → Package Settings → SublimeLinter → Settings - 在右侧用户设置中加入：
{
"linters": {
"ruff": {
"executable": ["/Users/you/.local/bin/ruff"]
}
}
}
注意：
-
executable必须是数组，哪怕只有一个路径也要写成["/path/to/ruff"] - 别用
~，Sublime 不展开波浪号；用which ruff在 Sublime 终端里查真实路径 - Windows 用户填
["C:\Users\xxx\AppData\Roaming\Python\Scripts\ruff.exe"]，反斜杠要双写 - 如果用
pipx install ruff，路径通常是~/.local/bin/ruff（macOS/Linux）或%APPDATA%PythonScripts uff.exe（Windows）
pyproject.toml 必须显式启用 I/D/UP 规则
Ruff 默认只检查 E（语法错误）、F（PyFlakes）、W（警告），但 Python 开发者日常依赖的导入排序（I）、docstring 检查（D）、语法升级提示（UP）全都不在默认集里。
如果你只写了：
[tool.ruff] select = ["E", "F", "W"]
那 import sys 后没使用，ruff 就不会报 F401——因为 F401 属于 I 类规则，不在 select 列表里。
推荐最小可用配置：
[tool.ruff] select = ["E", "F", "W", "I", "D", "UP"] ignore = ["E501"] # 行长限制可按需忽略
关键点：
-
pyproject.toml必须放在项目根目录，且 Sublime 当前打开的是该目录（不是单个 .py 文件） - SublimeLinter-contrib-ruff 不支持
ruff.toml，只认pyproject.toml - 修改
pyproject.toml后，需要重启 Sublime 或重新加载项目（Project → Close Project再重开）
为什么 Ruff 错误不实时高亮，只在保存后出现？
默认 lint_mode 是 "background"，但 SublimeLinter-contrib-ruff 实际行为更接近 on_save，尤其在大文件或规则较多时——这是插件实现限制，不是配置错。
你可以尝试强制开启实时检查，但要注意副作用：
- 在 SublimeLinter 用户设置里加：
"lint_mode": "background" - 同时设
"delay": 0.3（单位秒），避免每敲一个字符都触发检查 - 若仍卡顿，说明当前
ruff check调用太重，建议改回"lint_mode": ["on_save"]
真正影响响应速度的，其实是 ruff 自身的冷启动时间。首次调用时，Rust 二进制加载、规则解析、AST 构建会花 100–300ms。后续调用快很多，但 Sublime 每次都新开进程，没法复用——这点和 VSCode 的语言服务器模式本质不同。
所以别指望它像 ESLint 那样“输入即报错”。它的定位是快速扫描 + 保存时反馈，不是 IDE 级实时分析。
