Pylint 和 Flake8 是我在 Python 项目里搭质量防线时最先装上、也最常被讨论的两个工具。很多人觉得“代码能跑就行lint 不过是找茬”但当你被一个藏在角落的未使用变量坑过、被一段复杂度爆表的函数拖到不敢重构之后就会明白静态检查其实是最便宜的质量防线。这篇文章不讲高大上的理论而是围绕“代码质量卫士”这一定位把 Pylint 和 Flake8 的分工、配置、实战输出、CI 集成和常见坑一次说清楚。无论你是刚开始接触静态检查的 Python 开发者还是正在给团队搭建质量规范的负责人都可以从这里找到一套能直接抄作业的方案。1. 先搞清分工Flake8 快速找错Pylint 深度盘问在动手配置之前有个关键问题必须想明白Flake8 和 Pylint 并不是同一个工具的两种包装它们的检查思路完全不同。有人会问“既然都用为什么不只装一个”答案是“因为它们查的不是同一层东西”。如果拿体检来类比Flake8 像门口的量血压和体重秤几秒钟出结果能筛掉大部分明显异常Pylint 更像专科医生的系统问诊速度慢一些但能发现血压计看不出来的隐患。1.1 Flake8 是“快刀”静态检查里的轻骑兵Flake8 本质上是三个工具的组合PyFlakes 负责找逻辑错误pycodestyle 负责查 PEP8 风格McCabe 负责计算圈复杂度。官方文档里说得很直白它就是把这些检查器包在一个命令行工具后面让团队少记三个命令。因为检查方式基于源码扫描不做太多跨文件推理所以速度非常快一个中等规模项目跑下来通常就是几秒钟。具体到能查什么Flake8 最擅长的是这几类未使用的导入和变量、导入后没被引用的模块、代码里明显的语法问题、命名风格不符合 PEP8、行太长、缩进错误以及函数复杂度过高。举个例子你写了一句import os但整个文件根本没用到Flake8 会直接甩出F401你定义了一个局部变量却从没读过Flake8 会报F841你写完一个函数分支多得让人头皮发麻McCabe 的C901会提醒你复杂度已经超了红线。我实际用下来的感受是Flake8 的“误报率”很低因为它查的东西基本是客观事实。它不会跟你讨论“这段代码设计好不好”它只关心“这个变量确实没用到”“这行确实超过了行宽”。这种特性让它非常适合做提交前的第一道闸门反馈足够快噪音足够少团队接受度高。1.2 Pylint 是“重盾”能看穿逻辑问题的深度扫描Pylint 的定位比 Flake8 高一个量级。它也是基于代码分析但分析的不只是表面语法而是会构建抽象语法树并结合上下文去做检查。因此它能发现一堆 Flake8 看不见的问题。最典型的是可变默认参数比如def foo(x, items[])Flake8 不会吭声Pylint 会直接指出这是危险默认值W0102因为默认列表在多次调用之间会被共享。这种问题平时不炸炸起来就是“明明没修改列表数据怎么串了”的灵异事件。Pylint 还会检查异常捕获是否过宽。你写一个except Exception:想兜住所有错误Pylint 会警告你这是在吞异常让你去捕获更具体的类型。它甚至会检查未使用的函数参数、函数参数数量是否过多、类里的属性是否过于膨胀、模块里的重复代码等等。检查项按类别分得很细C 是约定类R 是重构建议W 是警告E 是错误F 是致命问题。最后它还会给整个项目打一个 0 到 10 的质量分。代价也很直观慢。Pylint 跑一个项目往往从几秒到几十秒不等项目越大越明显。而且默认配置下手比较“碎”经常连缺模块 docstring 都管所以刚上手的人很容易被一堆 C 类建议淹没。我的建议是别被它吓到Pylint 的价值恰恰藏在那些 Flake8 查不到的 warning 里尤其是重构前跑一轮能帮你提前预估风险点。1.3 一张表看懂两边的差异为了方便决策我把二者的关键差异整理成了一张对照表维度Flake8Pylint检查核心PyFlakes pycodestyle McCabe基于抽象语法树的深度静态分析速度快毫秒到秒级慢秒到分钟级风格检查内置 PEP8 规则部分覆盖但不如 Flake8 细逻辑风险检查较弱很强例如可变默认值、异常捕获过宽误报率低默认偏高需要配置调教配置成本低开箱即用高规则多需要团队约定典型场景提交前快速检查、CI 第一道门深度 review、重构前的风险扫描看到这里结论已经很明显了这不是二选一的问题而是分工配合的问题。Flake8 负责快速兜底Pylint 负责深度体检。把两者都纳入日常工作流才算真正把“代码质量卫士”这个角色配齐了。2. 动手落地从安装到一份不会被同事吐槽的配置很多教程一上来就丢配置却不解释为什么。结果就是大家复制粘贴一长串disable项目质量没守住反而多了很多“工具豁免”。这一节我按实际搭建流程来讲先解释环境再给最小可用配置最后用 pre-commit 把它固定到提交流程里。2.1 环境隔离与版本锁定安装命令本身没什么好说的但强烈建议在虚拟环境里装不要直接怼到全局 Python。你可以用venv或poetry如果是刚起步的项目直接用下面这套最简单python -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install pylint3.2.6 flake87.1.1为什么要锁版本这一点新手最容易忽略。Pylint 和 Flake8 都在持续迭代新版本可能调整默认规则、修改错误码、优化性能。如果你的同事 A 用的是 Pylint 2.x同事 B 用的是 Pylint 3.x那同一段代码在不同机器上可能得到完全不同的检查结果。锁版本不是矫情是让“质量红线”这件事具备可复现性。建议把这两个工具连同版本号写进requirements-dev.txt或者放到pyproject.toml的开发依赖组里。还有个小技巧安装完成后用flake8 --version和pylint --version确认一下版本。如果团队里有 CI更要确保 CI 里装的版本和本地完全一致否则就会出现“本地全绿、CI 飘红”的尴尬局面。2.2 一套能“跑起来”的最小配置我见过太多人一上来就抄网上的“终极配置”几十条 disable 堆在那里最后工具形同虚设。正确做法是先给一个最小的、符合常规需求的配置跑一阵子后再根据真实投诉逐条调整。Flake8 的配置放在.flake8文件里就行下面是我常用的基线配置[flake8] max-line-length 88 exclude .git,__pycache__,build,dist,.venv,venv,migrations extend-ignore E203,W503max-line-length 88是为配合 Black 格式化器因为 Black 默认就把行宽压到 88。exclude的意思很清楚别去检查第三方库、虚拟环境、迁移脚本这些不需要守规矩的地方。extend-ignore则是用来处理 Black 和 PEP8 的两个已知冲突E203 是冒号前有空格W503 是换行时二元运算符在最前面Black 的格式化风格就喜欢这样所以必须忽略否则每次格式化完都会被 Flake8 投诉。Pylint 的配置建议放在pyproject.toml的[tool.pylint]段里目录更整洁[tool.pylint] py-version 3.11 jobs 0 fail-under 8 good-names [i, j, k, ex, Run, _, main] disable [ C0114, C0115, C0116, ]jobs 0表示用满所有 CPU 核能明显加速。fail-under 8意思是如果评分低于 8 分Pylint 会以非 0 状态退出方便接进 CI。good-names用来放那些系统约定俗成的短名字比如循环变量i、异常变量ex、Django 的Run不然后台会疯狂给你报 C0103。最后这个disable列表我只关了三个 docstring 相关的约定类规则。如果你所在团队还没有建立“每个模块、函数、类必须写 docstring”的规范这三条会制造大量噪音。但请注意我特意没把W0718异常捕获过宽这类真正的风险项放进去因为那些不该被轻易关掉。2.3 让检查变成“提交前自动触发”的钩子配置好之后最怕的就是“记得就跑不记得就跳过”。所以下一步一定要把这个检查挂进 git pre-commit 钩子。这里我强烈推荐 pre-commit 这个工具它能把 Flake8、Pylint、Black、isort 等工具统一管理起来。先安装并写配置pip install pre-commit在项目根目录建.pre-commit-config.yamlrepos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.6.0 hooks: - id: trailing-whitespace - id: end-of-file-fixer - repo: https://github.com/pycqa/flake8 rev: 7.1.1 hooks: - id: flake8 additional_dependencies: [flake8-bugbear24.4.26] - repo: https://github.com/pylint-dev/pylint rev: v3.2.6 hooks: - id: pylint args: [--fail-under8]然后执行pre-commit install pre-commit run --all-filespre-commit install会在.git/hooks里生成本地钩子之后每次git commit都会自动跑规则。pre-commit run --all-files是第一次手动跑全量把存量问题一次性暴露出来。这里有个经验如果项目已经很大第一次跑全量往往会爆出几百个问题不要慌不要急着在配置里到处 disable先把新增代码管住存量问题慢慢降级解决。3. 用一个反面案例跑一遍完整检查纸上谈兵没意思我准备了一个故意埋了雷的示例文件通过真实输出带你看看 Flake8 和 Pylint 到底能挖出什么东西。3.1 一个看似正常、实则处处有隐患的样例假设项目里有个app/main.pyA sample module with intentional issues. import json import os import sys from datetime import datetime cache {} def process_data(data, debugFalse, options{}): Process incoming data. result [] for item in data: if item % 2 0: result.append(item) else: continue if debug: debug_info fprocessed{len(result)} print(processed count:, len(result)) return result def format_report(items, prefixLOG): Format each item into a string with timestamp. timestamp datetime.now().isoformat() lines [] for item in items: lines.append(f{timestamp}: {prefix}: {item}) return lines def main(): Run the demo pipeline. numbers [1, 2, 3, 4] result process_data(numbers, debugTrue) report format_report(result) print( | .join(report)) try: value int(os.environ.get(DEMO_NUMBER, not-a-number)) print(value) except Exception as exc: print(caught error:, exc) if __name__ __main__: main()这段代码能正常运行表面看不出毛病。但如果你把静态检查跑起来问题就藏不住了。先跑 Flake8python -m flake8 app/输出大概是这样的app/main.py:2:1: F401 json imported but unused app/main.py:3:1: F401 sys imported but unused app/main.py:18:12: F841 local variable debug_info is assigned to but never used三条红线全部命中两个导入根本没用一个局部变量赋了值却从没读过。这类问题靠肉眼很容易漏但留着它就是在给未来埋“我明明 import 了怎么还是报错”的坑。再跑 Pylintpython -m pylint app/输出会丰富得多app/main.py:2:0: W0611: Unused import json (unused-import) app/main.py:3:0: W0611: Unused import sys (unused-import) app/main.py:6:0: W0612: Unused variable cache (unused-variable) app/main.py:9:0: W0613: Unused argument options (unused-argument) app/main.py:10:25: W0102: Dangerous default value {} as default argument (dangerous-default-value) app/main.py:43:0: W0718: Catching too general exception Exception (broad-exception-caught) Your code has been rated at 6.10/103.2 逐行解读这些警告背后的含义先看 Flake8 报的F401这没什么好争论的删掉两行 import 就行。F841则是说debug_info这个变量从头到尾都没用过。这种代码通常是调试时临时写的忘了清掉Flake8 就是在提醒你“这行要么用起来要么删掉”。Pylint 提供的警告更有意思。W0612是说模块级变量cache从头到尾没被引用。如果它只是留给未来用的建议先删掉等真正需要时再加别让“预留”变成垃圾代码。W0102是最需要注意的options{}会让所有调用这个函数的对象共享同一个字典实例。正确写法是改成optionsNone函数开头再加一句if options is None: options {}这样每次调用都会生成独立字典。W0718对应的是except Exception:。在真实项目里这种写法会让程序连KeyboardInterrupt、MemoryError都能被静默吞掉排查问题时极其难受。我的建议是把它改成明确的异常类型比如这里int()转换可能只抛出ValueError那就写except ValueError as exc:。如果确实希望兜底至少要except (ValueError, TypeError) as exc:并加上日志记录。看到 6.10 分这个数字也别慌。它不代表项目“不及格”而是给你一个基线。我们要盯的是趋势这次 6.10下次重构后 7.20说明方向对了。硬性要求 8.0 分以上是对新代码的一种约束。3.3 合理降噪不是所有警告都要修很多人用完 Pylint 后被大量 C 类约定建议烦得不行于是到处搜配置把所有规则都禁用这是舍本逐末。降噪的正确姿势是分三步第一区分“约定类”和“风险类”。docstring 缺失是约定问题团队暂时不强制可以禁用但可变默认参数、异常捕获过宽、未处理废弃函数这些属于风险类不要轻易关。第二能局部禁用就不要全局禁用。如果只是某个函数因为框架要求必须多一个没用的参数最优雅的写法是# pylint: disableunused-argument def handler(request, context): return pong这比在配置文件里把unused-argument全局关掉要安全得多因为它只放行了这一行后续代码里的同样问题还会被抓出来。第三Flake8 的# noqa注释必须带上具体错误码。比如return x # noqa: E501比单纯写# noqa强得多后者会把这一行所有潜在问题都盖住。我的原则是永远不追求“零警告”。如果为了凑零警告把项目配置成一只纸老虎那不如不装工具。真正有价值的指标是“每次提交的新代码里有没有新增的警告”而不是“历史警告总数是不是清零”。4. 在 CI 里卡住质量红线增量检查与性能优化本地配置好只是第一步如果只有本地钩子总有人会想办法绕过或者换台机器就忘了装。真正让规则有约束力的是把它接进 CI。这一节讲一些命令行技巧、GitHub Actions 的落地写法以及怎么解决 Pylint 慢的问题。4.1 命令行花式用法不只是flake8 .很多人在终端只会敲一句flake8 .这当然没问题但在真实项目里我们常常需要更精准的控制。比如只想检查本次改动的文件避免历史存量噪音干扰git diff --name-only --diff-filterACM origin/main...HEAD -- *.py | xargs python -m flake8git diff拿到改动文件名管道交给 Flake8。这样即使项目里有一万行历史遗留问题也不会淹没你这次改动的真实结果。想看看问题集中在哪类规则上可以用统计模式python -m flake8 app --statistics它会按错误码分类汇总让你一眼看出“项目里 80% 的投诉都是 E501 行太长”那你就知道该调行宽配置还是加强格式化。Pylint 这边建议用输出格式把结果变成机器可读的 JSON方便对接其他工具python -m pylint app --output-formatjson pylint-report.json另外--fail-under是 CI 里的关键参数。它不是摆设而是把“质量分数”变成硬性指标。比如团队约定 8.0 分是及格线那命令行就可以写成python -m pylint app --fail-under8只要评分低于 8.0命令就返回非 0 退出码CI 随之失败。4.2 在 GitHub Actions 中设置一条真正的质量红线假设你的仓库托管在 GitHub下面这套 workflow 可以保证每次有人提交 pull request系统只检查本次改动涉及的文件Flake8 一个错都不放过Pylint 评分低于 8.0 就拒绝合并。name: lint on: pull_request: jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install dependencies run: | pip install flake87.1.1 pylint3.2.6 - name: Run Flake8 on changed files run: | files$(git diff --name-only --diff-filterACM origin/main...HEAD -- *.py) if [ -n $files ]; then python -m flake8 $files fi - name: Run Pylint on changed files run: | files$(git diff --name-only --diff-filterACM origin/main...HEAD -- *.py) if [ -n $files ]; then python -m pylint $files --fail-under8 fi这里有个需要解释的点为什么只检查改动文件而不是全项目因为存量问题不是一朝一夕能解决的如果你在 CI 里一上来就要求全项目 Flake8 零错误那第一个跑 CI 的同事会被几百个历史问题活活劝退。增量检查能保证一件事你新写的代码必须干净历史问题另算。这是团队落地质量工具时最有效的破冰策略。fetch-depth: 0是为了让 GitHub Actions 能拿到完整的 git 历史否则origin/main可能不存在diff 命令会失效。如果项目还在早期你也可以把origin/main...HEAD换成HEAD~1...HEAD效果是只看最后一次提交。4.3 Pylint 太慢了怎么办三个立竿见影的方向Pylint 慢是绕不开的话题尤其是中大型项目全量扫描可能跑到一分钟以上。在 CI 里这会让整个流水线变得非常磨人。我提供三个方案按性价比从高到低排列。第一充分用多核。Pylint 支持-j参数-j 0表示自动使用所有 CPU 核。本地开发机器多核很常见这个参数基本能带来 3 到 5 倍的速度提升。如果你在 CI 上怕吃满资源可以固定-j 2或-j 4。第二缩小扫描范围。通过配置文件里的ignore排除migrations、scripts、tests里那些不需要严格质量约束的文件。迁移脚本本来就是一次性代码被unused-import这类规则轰炸毫无意义。第三配合增量检查只跑改动文件。把上一节提到的git diff思路放到 CI 里你会惊喜地发现 Pylint 从几十秒降到了几秒。另外Pylint 3.x 相比 2.x 在性能上有明显提升。如果你还在用老版本升级一次可能比你想办法调优更划算。如果真到了大型单体项目怎么优化都嫌慢的程度可以考虑引入 Ruff 作为 Flake8 的替代品或者只把 Pylint 放到每天定时任务和发布前的深度检查里而不是每个 PR 都跑全量。根据团队节奏来规则是为人服务的。5. 进阶玩法插件、配合 Black还有我踩过的坑工具用得越久越会发现默认能力只是起点。Flake8 和 Pylint 都有插件生态能覆盖 Django、pytest、数据类等具体场景。同时如果项目里用了 Black 和 isort你还需要处理格式化风格与 lint 规则的冲突。这一节是干货浓度最高的部分。5.1 让 Flake8 更“懂业务”的常用插件Flake8 本身不查 docstring也没有那么多坑爹模式但装上几个插件后它的能力会提升一大截。我最常用的是下面这几个pip install flake8-bugbear flake8-builtins flake8-comprehensionsflake8-bugbear是目前社区认可度很高的插件会补充一批 B 开头的规则比如可变默认参数、循环里的闭包陷阱、except:裸捕获等。flake8-builtins会检查你是否不小心覆盖了 Python 内置函数名比如把变量命名为list或dict。flake8-comprehensions会建议你把简单的for循环改写成列表推导式减少冗余代码。安装完之后注意要在 Flake8 配置里让这些插件规则生效。如果你用的是.flake8文件可以这样补充[flake8] extend-select Bextend-select的作用是“在默认规则之外再显式开启这些插件规则”。这样你就不会因为安装插件后觉得规则太吵又把它们关回去。插件不是越多越好每装一个插件都意味着团队要多接受一批检查规则宁可少而精也不要堆到让人麻木。5.2 Pylint 与 Django、pytest 的场景适配Pylint 默认情况下对 Django 和 pytest 的代码会产生大量误报。比如 Django 模型里的objects字段Pylint 会看成“没有这个属性”pytest 的fixture参数Pylint 会当成“未使用的函数参数”。这不是 Pylint 不行而是它不够了解这些框架的约定。解决办法是别手动 disable而是装官方插件。Django 项目装pip install pylint-django然后在pyproject.toml中启用[tool.pylint] load-plugins [pylint_django] django-settings-module config.settings这样 Pylint 就能识别models.Model、objects等 Django 约定误报数量会明显下降。pytest 项目同理装pylint-pytest它会让 fixture 参数被正确识别而不是被当成未使用变量。插件本质上是“给工具的规则库补充领域知识”这是比堆disable更聪明、更精准的做法。5.3 和 Black、isort 的配合一次把格式化冲突理清如果项目里同时使用 Black 和 isort你会发现 Flake8 的默认规则和它们的格式化风格经常“打架”。最经典的冲突有两个一个是行宽PEP8 默认建议 79Black 默认是 88另一个是二元运算符换行位置PEP8 传统上要求运算符放在行首Black 则喜欢把运算符放在行尾。不处理这个冲突会出现一个非常蠢的循环Black 格式化完代码Flake8 报错你手动改回去Black 又格式化回来最后你只能疯狂加# noqa。正确解法是在配置里明确告诉 Flake8我已经用 Black 了以下规则请闭嘴[flake8] max-line-length 88 extend-ignore E203, W503isort 那边要设置成 Black 风格[tool.isort] profile blackPylint 同样需要对齐行宽在[tool.pylint]里把line-too-long和W503加进 disable。这不是为了纵容坏代码而是为了尊重团队的格式化工具。格式化器负责风格统一静态检查器负责更深层的质量问题这个分工一旦混乱整个流程就会陷入无休止的格式争吵。5.4 我踩过的坑和现在的最终工作流最后分享几个真金白银换来的教训。第一个坑是盲目复制网上的长配置。我曾见过一个团队的pyproject.toml里列了上百条disable结果 Pylint 几乎成了摆设。配置文件是需要“生长”的新项目宁可少关规则跑几个月再根据真实投诉调整也不要第一天就全部关完。第二个坑是# noqa不带错误码。有人为了让 Flake8 闭嘴在行尾写一个孤零零的# noqa结果这一行后续所有风格问题都被掩盖了。正确写法是# noqa: E501只豁免那一个问题。第三个坑是存量项目直接上全量检查。第一次跑 Pylint 看到几百个问题很容易让团队产生抵触情绪。最稳妥的策略是新代码严格过 lint历史遗留问题单独建一个 backlog每轮迭代顺手清理几个。等存量问题慢慢少了再把fail-under从 6.0 提到 7.0再提到 8.0。我现在的工作流很固定先写代码再让 Black 和 isort 自动格式化然后 pre-commit 钩子里 Flake8 做快速检查Pylint 做深度检查最后才是跑测试和提交。CI 里再跑一遍增量检查作为本地钩子的兜底裁判。可以说Flake8 和 Pylint 从来不是为了制造麻烦而是把那些“本可以早点发现”的问题挡在代码评审和测试阶段之前。用了几年的体会是我对 Pylint 分数的态度已经从“必须 10 分”变成了“盯住趋势”。10 分是理想但为了 10 分把规则关得七七八八完全失去意义。我更在意每次提交的 diff 里有没有新增的警告更在意那些能引导我发现真实 bug 的 warning 有没有被重视。如果你刚开始搭这套体系别追求一步到位先把 Flake8 跑起来再慢慢加 Pylint等团队习惯了这两道防线你会发现 code review 的时间真的能省下一大半。