Ruff 0.14 系列版本演进全解析15 次迭代中的规则、格式化器、抑制机制与 CLI 能力升级【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruffRuff 0.14 系列是 2025 年 10 月至 2026 年 1 月间连续发布的 15 个版本0.14.0 – 0.14.14核心围绕「规则修复的确定性」「范围化抑制range suppression的完整闭环」「预览规则从实验走向稳定」三条主线展开。本文以仓库内 changelogs/0.14.x.md 为骨架逐一解读每个版本的 Breaking change、新增规则、修复安全性与 CLI/Server 变化并对照crates/ruff_linter下的源码与快照测试帮助你判断哪些新能力可以直接用于生产、哪些仍处于 preview 阶段需要显式开启。说明本文所述版本均已完成发布周期当前仓库主版本线已推进至 0.16.5见 crates/ruff/Cargo.toml0.14.x 的 changelog 是理解该系列演进脉络的完整历史记录。0.14 系列总览每周一版的高频迭代从 changelog 的发布时间看0.14 系列基本保持每周一版约 7 天的节奏覆盖规则、格式化器、CLI、LSP Server、性能与文档六个方向。全部版本号与发布日如下版本发布时间主要看点0.14.02025-10-07默认与最新 Python 目标升级到 3.14Breaking0.14.12025-10-16实现DOC102格式化器适配 Python 3.14 异常元组0.14.22025-10-23ruff ruleJSON 输出增强INT001–INT003名称解析0.14.32025-10-30新增PLR1708--watch尊重--output-format0.14.42025-11-06ruff analyze graph支持 notebook格式化器 lambda/函数头0.14.52025-11-13--add-noqa支持原因注释--help着色0.14.62025-11-21终端超链接渲染ruff analyze跳过TYPE_CHECKING导入0.14.72025-11-28新增RUF066统计输出展示部分可修复指标0.14.82025-12-04PTH104等标记 unsafeGitLab 集成建议--output-file0.14.92025-12-11新增RUF100范围抑制诊断与PLW0133memchr提速0.14.102025-12-18新增ISC004方法链 fluent 格式化0.14.112026-01-08新增RUF067范围抑制诊断合并Python 3.15 预览支持0.14.122026-01-15RUF100/RUF066微调WASM 显式日志初始化0.14.132026-01-15与 0.14.12 内容完全一致WASM 发布问题后的补发0.14.142026-01-22新增RUF068大批修复改为「删除注释即 unsafe」其中 0.14.12 与 0.14.13 是同一内容因 WASM 包发布故障0.14.12 没有对应的 GitHub release 与 Git tag但其包已发布到 PyPI故补发内容完全一致的 0.14.13。这个细节提醒我们以 changelog tag 双重校验版本真实性PyPI 上的包版本可能与仓库 tag 存在短暂错位。Breaking changePython 3.14 成为默认目标版本0.14.0 的唯一 Breaking change 是将默认与最新支持的 Python 版本更新为 3.14对应上游改动 #20725。其直接后果是未显式配置target-version的项目解析与规则判定基准从 Python 3.13 迁移到 3.140.14.1 将 README 中的 Python 兼容性说明从 3.13 更新为 3.140.14.11 进一步在preview模式下允许Python 3.15作为合法的target-version取值为下一版语法特性预留空间。Python 版本感知不只影响语法解析还直接驱动若干格式化与规则行为例如 0.14.1 的 preview 改动Python 3.14 下多异常类型如except (A, B)不再强制加括号——这是因为 Python 3.14 起该写法无需括号即可生效Ruff 据此在target-version 3.14时移除冗余括号。类似的版本门控逻辑遍布 crates/ruff_python_ast/src/python_version.rs 与 crates/ruff_python_formatter 的各个表达式模块中。预览新规则巡礼从 F 系到 R 系0.14 系列在预览通道需配置preview true中落地了多条全新规则。按引入版本排列版本规则所属插件说明0.14.1DOC102pydoclintdocstring-extraneous-parameterdocstring 中声明了函数签名不存在的参数0.14.3PLR1708pylintstop-iteration-return在生成器内显式return next(...)/StopIteration0.14.7RUF066ruff检测不必要的类属性如误加property的普通方法0.14.9PLW0133pylint检测内建异常的非法子类化0.14.10ISC004flake8-implicit-str-concat容器字面量中隐式字符串拼接0.14.11RUF067ruffnon-empty-init-module__init__.py非空但仍声明为包0.14.14RUF068ruff检测__all__中的重复条目RUF066 / RUF067 / RUF068Ruff 自研规则的可观测演进这三条新规则恰好展示了 Ruff 自家ruff规则族代码 6xx 段的完整开发链路源码均可直接查看RUF066property-without-return实现在 crates/ruff_linter/src/rules/ruff/rules/property_without_return.rs。它捕获「写了property但方法体内不含return」的低级错误0.14.12 起还开始尊重lint.pydocstyle.property-decorators配置即用户自定义的property风格装饰器也会被识别RUF067non-empty-init-module实现在 crates/ruff_linter/src/rules/ruff/rules/non_empty_init_module.rs。从源码注释可见其灵感来自flake8-empty-init-modules并依据 PEP 562 允许__init__.py只保留 docstring、属性 docstring 与 re-exportimport/from ... import其余语句都会触发诊断RUF068duplicate-entry-in-dunder-all实现在 crates/ruff_linter/src/rules/ruff/rules/duplicate_entry_in_dunder_all.rs。三条规则在插件级测试入口 crates/ruff_linter/src/rules/ruff/mod.rs 中均有对应#[test_case]如RUF066.py、RUF067/modules/__init__.py、RUF068.py快照文件位于同目录snapshots/下可作为「什么算触发、什么不算」的行为契约。跨插件新规则DOC102、PLR1708、PLW0133、ISC004DOC102属于 pydoclint 系列0.14.1 首次落地0.14.5 补上 NumPy 风格逗号分隔参数的解析支持其姊妹规则DOC501/DOC502在 0.14.3 修复了显式重新抛出异常的误报PLR1708stop-iteration-return实现在 crates/ruff_linter/src/rules/pylint/rules/stop_iteration_return.rs并在 0.14.7 修复了嵌套函数中的误报——这说明新规则的首个 preview 版本普遍会经历一轮「误报收敛」PLW0133于 0.14.9 加入用于捕获class MyError(BaseException)这类覆盖内建异常语义的写法ISC004隐式字符串拼接实现在 crates/ruff_linter/src/rules/flake8_implicit_str_concat/rules/collection_literal.rs针对列表/元组/集合/字典字面量元素间的隐式拼接与前缀规则ISC001–ISC003形成互补。开启上述规则的典型 pyproject 片段如下以RUF067、PLR1708为例[tool.ruff] preview true # 新规则默认走 preview 通道 [tool.ruff.lint] select [RUF, PL]preview开关的语义请参见 docs/preview.md未开启 preview 时处于 preview 状态的规则即使被select选中也不会报错只会输出提示。修复安全性的收紧0.14 系列最重要的行为变化整个 0.14 系列反复出现的主题是对 autofix 安全性的精细化治理方向有两个safe → unsafe 降级以及「可能删除注释的修复一律视为 unsafe」。方向一将过度自信的修复标记为 unsafe0.14.1B905zip()缺strict参数与B912的修复被标记为 unsafe0.14.2进一步约束B905/B912——当迭代对象少于两个且无星号参数时直接跳过避免「补严格模式」的修复改变语义0.14.8flake8-use-pathlib的PTH104、PTH105、PTH109、PTH115修复因可能改变返回类型而被标记 unsafe0.14.10 又扩展到复合语句中的类型变化场景0.14.11FURB192的修复被标记为「始终 unsafe」PLW1510的修复降级为仅展示display-only。对使用者而言修复安全级别直接决定ruff check --fix是否自动应用safe 修复默认执行unsafe 修复需要追加--unsafe-fixes才会应用。因此升级到 0.14 系列后某些此前自动修改的代码可能不再被改写这属于刻意为之的安全设计。方向二「会删除注释的修复一律 unsafe」——0.14.14 大规模调整0.14.14 是这一策略的集大成者凡在修复时会移除用户注释的规则其修复全部降级为 unsafe涉及flake8-bugbear的B009/B010/B013/B014/B033flake8-simplify的SIM910/SIM911pyupgrade的UP007/UP039/UP041/UP045refurb的FURB105/FURB116/FURB136/FURB140/FURB145/FURB154/FURB157/FURB164/FURB181/FURB188以及ruff的RUF019/RUF020共 23 条。注释通常是开发者留下的关键意图信息Ruff 团队选择「宁可少自动修复也不静默吞掉注释」这是 0.14 系列在工程可预期性上最重要的信号。修复分类的运行时判断可在 crates/ruff_diagnostics/src/fix.rs 与 crates/ruff_diagnostics/src/edit.rs 中查看每条Fix均携带适用性applicability标记check命令在应用前会统一校验。各规则文档页由 crates/ruff_dev/src/generate_docs.rs 生成也同步标注了修复安全性与示例。范围抑制Range Suppression机制的闭环从实验到自检0.14 系列在「注释级抑制」上走完了「能用 → 能查 → 能报错」三步0.14.9RUF100新增对未使用范围抑制# ruff: disable/# ruff: enable成对注释的诊断。此前RUF100只负责清理无效的# noqa实现见 crates/ruff_linter/src/rules/ruff/rules/unused_noqa.rs现在范围抑制注释若与诊断不匹配也会被报告0.14.11为成对的disable/enable抑制注释合并诊断输出并开始报告无效或未匹配的范围抑制注释相关逻辑集中在 crates/ruff_linter/src/suppression.rs 与 crates/ruff_linter/src/noqa.rs0.14.14进一步合并范围抑制代码的诊断将同一行多个抑制代码的提示收敛减少噪音。配套地0.14.9 文档更新重新组织了抑制机制说明并涵盖*.pyw在 preview 下的默认纳入行为0.14.10 让ERA001忽略ruff:disable/ruff:enable注释避免「清除注释代码」与「范围抑制」互相打架。从 crates/ruff_linter/src/noqa.rs 的Directive::All/Directive::Codes枚举可以看出Ruff 的抑制体系统一建模了文件级豁免、# noqa与范围化disable/enable三类指令0.14 系列只是把校验与自检补齐。格式化器Formatter预览能力Python 3.14 语法与可读性并进0.14 系列的格式化器改动集中在 preview 通道既追赶 Python 3.14 语法也改善长表达式布局0.14.1Python 3.14 移除多异常类型外的冗余括号配合target-version判断0.14.4允许「无 docstring 的函数头之后换行」为带as捕获的长match模式避免多余括号0.14.6修复一元表达式、属性表达式中的注释格式化 panicfmt: skip对单行复合语句生效0.14.10方法链的 fluent 格式化长链式调用的换行分组与 lambda 参数单行化正文超宽时才整体加括号换行0.14.14lambda 正文保留必要括号。其中fmt: skip的两处修复0.14.6 处理单行复合语句、0.14.12 扩展到同一逻辑行多条语句表明该注释指令在多语句场景下曾存在覆盖盲区升级后行为更一致。Ruff 与 Black 在 lambda 布局等细节上的已知差异在 0.14.10 被显式文档化见 docs/formatter.md 与 docs/formatter/black.md做格式迁移前建议先读这两篇。CLI 与机器可读输出的现代化0.14 系列对命令行做了大量「面向自动化与编辑器」的改进ruff ruleJSON 输出增强0.14.2并在 0.14.5 将上游 linter 的 URL加入ruff linter --output-formatjson对应实现见 crates/ruff/src/commands/linter.rs--watch尊重--output-format0.14.3监听模式下也能输出 JSON 等格式补齐了增量场景的机器可读性终端超链接渲染0.14.6lint 错误在支持的终端中渲染为可点击链接0.14.11 又修复了多行诊断的 GitHub 格式--help着色0.14.5与统计输出的部分可修复指示0.14.7改善人机界面--add-noqa支持原因参数0.14.5可为生成的# noqa注释附上 reason类似# noqa: F401 -- 说明方便追溯ruff analyze graph支持 notebook0.14.4并在 0.14.6 增加跳过TYPE_CHECKING块内导入的选项、0.14.11 支持将配置的src目录纳入图谱解析。这些命令的实现集中位于 crates/ruff/src/commands如add_noqa.rs、analyze_graph.rs、rule.rs、check.rs命令帮助文本由 crates/ruff_dev/src/generate_cli_help.rs 生成并固化为快照测试保证文档与 CLI 行为同步。ServerLSP侧诊断推送与 notebook 支持编辑器侧ruff server源码见 crates/ruff_server在 0.14 系列也有关键修正0.14.3对支持 pull diagnostics 的客户端不再发送多余的「清除诊断」消息减少无效通信0.14.4修复 notebook 缺失诊断的问题——此前对.ipynb单元格的诊断存在盲区0.14.7为非规则诊断如配置错误设置正确的严重级别让编辑器能区分「代码问题」与「工具自身问题」。值得一提的是 0.14.1 与 0.14.2 使用DiagnosticTag为更多规则pyflakes、pandas 等添加了「过时/不建议使用」标签源码见 crates/ruff_linter/src/rules/pyflakes 与 pandas 相关规则目录这些标签会直接影响编辑器中的删除线等视觉呈现——0.14 系列正逐步把「语义信息」通过 LSP 标准协议透传给 IDE。解析器与性能错误恢复与 memchr 加速语法层在 0.14 系列收获了两类改进错误恢复error recovery0.14.1 起对未闭合字符串含 f-string、t-string显著改善恢复能力0.14.7 修复 IPython 转义命令表达式解析 panic后续版本持续处理await在函数外、f-string 引号嵌套、括号化上下文管理器等误报场景。解析器主体位于 crates/ruff_python_parser/src每条语法错误修正都有对应snapshots/快照性能0.14.9 使用memchr计算行索引crates/ruff_source_file/src/line_index.rs 是行索引实现处直接加速行定位0.14.1 还实现了整体二进制体积缩减。配置与错误提示的细节打磨0.14.3 起line-length超过阈值时给出更清晰的错误提示0.14.5 将上限显式对齐u16::MAX避免溢出0.14.11 将required-version的校验提前到规则解析之前——若 ruff 版本不满足要求直接终止而不是先报一堆规则解析错误这一改动影响启动顺序见 crates/ruff_workspace 的配置加载逻辑0.14.12 修复--show-settings输出的配置路径错误此前显示的可能是错误的配置文件位置。文档、贡献与版本自省的持续投入0.14 系列几乎每版都包含文档改动值得关注的信息治理动作包括0.14.2 开始在规则文档中标注规则的引入版本Since字段数据源见规则宏定义与 crates/ruff_dev/src/generate_rules_table.rs方便读者判断某条规则是否值得跟随升级0.14.9 完成抑制文档重组、0.14.12 新增llms.txt 支持——Ruff 官方文档开始面向 LLM/Agent 提供结构化入口多篇规则示例被改为「开箱即错」out-of-the-box即示例代码复制后无需改动即可触发对应规则0.14.5 为贡献指南新增「Opening a PR」章节0.14.12 引入prek于文档与 CI。升级到 0.14 的实践建议综合整个系列的变更升级时需要重点检查四类影响Python 3.14 默认值升级 0.14.0 后行为基准改变建议在[tool.ruff]中显式写明target-version避免隐式漂移配置参数详见 docs/configuration.md修复不再自动生效0.14.1、0.14.8、0.14.11 与 0.14.14 前后将大量修复降级为 unsafe。CI 中若依赖--fix自动改写需评估是否补充--unsafe-fixes同时接受语义/注释风险或改用--diff人工审查预览规则需显式开启DOC102、PLR1708、RUF066–RUF068、ISC004等新规则都需preview true。在项目配置中开启 preview 后可使用ruff check --preview先做干跑再正式合并范围抑制现在会被审计0.14.9–0.14.14 逐步让RUF100等规则检查# ruff: disable/# ruff: enable存量代码中失效的抑制注释会开始报错可在升级后运行一次ruff check --fix清理若需保留抑制注释请补上对应的真实代码规则。如果想逐条核对规则行为推荐直接阅读 crates/ruff_linter/src/rules 下对应插件的rules/目录及其snapshots/快照测试——每一条「0.14 新增/修复」都能在其中找到输入输出样例作为行为契约。【免费下载链接】ruffAn extremely fast Python linter and code formatter, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/ru/ruff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考