代码评审的时候，我经常在 PR 里看到三类东西：缩进一会儿空格一会儿 Tab，几个没用的 import 堆在那里，还有一个函数参数多到要翻两屏才看完。这种问题不算致命，但会反复出现——只要项目里没有一套自动化的检查机制，人工 Review 就会永远陷在这些琐碎里。所以两年前我做的第一个动作，就是给项目装上 Pylint 和 Flake8 这两道静态检查关卡，让机器先替人把明显的问题挡住。
这篇文章不是 Pylint 和 Flake8 官方文档的翻译，而是我先后在几个 Python 项目里把它们从"装了跑一下"到"真正写进开发和评审流程"的完整经验。适合刚接触静态检查的小白，也适合已经在用但觉得规则太吵、不知道该怎么配置的团队。我会尽量把里头的门道讲清楚：它们各自查什么、为什么两个都要、配置到底怎么写、以及怎样让团队愿意长期用而不是装完就扔。
1. 静态检查到底在查什么：先建立"代码质量"的共识
1.1 不运行代码就能查问题，是什么原理
先说明白一件事：Pylint 和 Flake8 都属于静态代码分析工具。所谓"静态"，指的是它们不真正执行你的代码，而是把源码当成文本来解析，在语法树和逻辑结构上做检查。因此它们跑得再慢也慢不到哪去，而且永远不会真的把你的数据玩坏。这跟单元测试、集成测试有本质区别——那些测试你要构造环境、准备数据、跑业务流程，而静态检查只要一行命令，几秒到几十秒就出结果。
我记得第一次用 Flake8 检查一个旧项目时，几十个文件瞬间就扫完了，列出来的问题五花八门：有没用的 import，有定义了却没用的变量，有一个函数缩进不一致导致的潜在语法歧义，还有一行长到 120 个字符的"火车代码"。这些问题是人眼很难在一遍遍 Review 里始终盯住的，但机器可以做到每次都一样严格。
这一节我想先帮大家建立一个共识：代码质量不是一个模糊的感性概念，而是一组可以被规则化、被自动验证的客观标准。Pylint 和 Flake8 就是把这套标准落地的工具。后面讲配置时你会频繁看到"规则"这个词，每个规则都有自己的编号和明确行为描述，这意味着团队里任何一个人都可以查文档搞清楚某条规则在说什么，而不是靠印象吵架。
1.2 Flake8 的三合一体质：风格、低级错误、复杂度
Flake8 其实不是单一的检查器，它默认把三个工具包在一起：pycodestyle 负责 PEP 8 风格检查，pyflakes 负责找出未使用变量、未使用 import、未定义名称这类逻辑硬伤，mccabe 负责计算圈复杂度。这三个角色分别可以理解成"排版校对员""低级错误探测器"和"复杂度雷达"。
pyflakes 那一层我特别喜欢，因为它几乎不会误报。它做的是纯粹的静态推导：某个名字在整个文件里 import 了但从没被用过，某段代码引用了不存在的变量，某个分支里的语句永远不可能执行到——这些结论都是确定的，不需要猜测代码意图。正因为如此，Flake8 在"门禁"场景特别管用，它说不行就是真的不行，团队里基本不会有人跟它争论。
mccabe 的圈复杂度衡量的是函数里独立路径的数量。比如一个函数有五个 if 分支加两个 for 循环，得分就会直线上升。这类函数往往是最容易藏 bug 的地方，因为调用者很难覆盖所有路径。Flake8 默认把复杂度阈值设在 10，超过就报警，这个数值本身就是一个很合理的起点。
1.3 Pylint 的体检范围：从命名到坏味道
Pylint 则走得更深。它不止查风格和明显的错误，还会分析函数参数数量、类的方法个数、模块里的重复代码比例、命名是否符合规范（比如函数名要小写加下划线、常量要全大写）、异常处理是否过宽、变量名是否与关键字冲突等等。可以说 Flake8 更像急诊分诊台，Pylint 更像一次全面体检，它会告诉你很多"现在没出问题，但长期看可能出事"的隐患。
举个例子，Pylint 会检查一个函数是否参数太多（默认超过 5 个就警告），是否在一个函数里做了太多事情（可以通过分支数量判断），甚至能识别出近似重复的代码块并给出相似度报告。这些能力对重构特别有帮助，尤其当你要接手的是一段三年前的祖传代码时，Pylint 的报告几乎就像一张先清哪块债的施工图。
那么到底用哪个？我的答案是两个一起用，但分工不同。下一节具体讲它们怎么配合。
2. Pylint 和 Flake8 的分工差异：为什么两个都要装
2.1 一张表看清两者的定位
先给一张对比表：
| 对比维度 | Flake8 | Pylint |
|---|---|---|
| 内核组成 | pycodestyle + pyflakes + mccabe | 独立分析引擎 |
| 检查重点 | 风格、低级错误、复杂度 | 命名、坏味道、重复代码、逻辑隐患 |
| 运行速度 | 快，秒级扫描大项目 | 较慢，大项目可能需要几十秒 |
| 误报率 | 低，规则边界清晰 | 偏高，需要配置调教 |
| 配置成本 | 低，几个参数就能开工 | 高，默认规则偏严，初期噪音多 |
| 典型场景 | CI 门禁、提交前快速检查 | 定期体检、重构辅助、深度 Review |
这表的结论很直接：Flake8 适合当"门卫"，因为又快又准；Pylint 适合当"家庭医生"，因为查得全但偶尔会小题大做，需要你给它划清楚边界。
我在项目里的实际组合是：pre-commit 阶段只跑 Flake8，几十毫秒出结果，不打断开发节奏；Pylint 放在 CI 里跑，生成完整报告，检查不达标就不允许合并。这样一个快一个慢、一个浅一个深，互相不干扰。
2.2 Pylint 能查到而 Flake8 查不到的典型问题
光说"查得深"太抽象，举几个具体例子。Flake8 的 pyflakes 能发现"变量定义了但没用"，但它不会管这个变量是不是命名不当；Pylint 则会把命名规范、参数数量、函数长度、模块内重复代码这些维度全部拉进来。
更关键的是 Pylint 能做一定程度的跨语句逻辑推理。比如它会发现某个 except 子句捕获了 Exception 却没有任何处理，只是默默吞掉错误，这在 Flake8 看来完全没问题，但实际是事故高发区。再比如它会在发现类里定义了某个方法但从未被使用时给出提示，帮助清理死代码。
还有一个我印象很深的能力是 Pylint 的"相似代码"检测。它默认会把超过四行且高度相似的代码块标出来，这对抓 Ctrl+C / Ctrl+V 出来的重复逻辑特别管用。我有一次在某个服务里跑了一遍，立刻发现两个工具函数长得几乎一模一样，只有参数名不同，顺手就合并了。这种问题靠 Code Review 很难发现，因为人眼扫过去会默认"这是两个函数"，而机器会告诉你"这俩是同一段代码的复制"。
2.3 为什么不是二选一，而是组合拳
有人会说 Flake8 已经能查风格和低级错误了，再加个 Pylint 是不是重复？我觉得不是。把代码质量的检查维度拆开看，风格层、语法错误层、逻辑隐患层、维护性层，每一层都需要不同的检查深度，Flake8 只覆盖前两层半，Pylint 才有能力触达后面两层。让一个工具扮演它不擅长的角色，结果就是配置越改越离谱，最后只能把规则全关掉。
反过来，如果只装 Pylint，它的噪音会让新人在入职第一周就产生"这工具是不是有病"的念头，团队很难坚持下去。所以最稳妥的路线永远是：先用 Flake8 把底线立住，再让 Pylint 作为深度体检工具逐步介入。这套组合在我的几个项目里跑了一两年，效果非常稳定。
3. 从安装到跑通：让两个工具先在自己的项目里转起来
3.1 安装命令和最简单的用法
安装没什么花头：
pip install flake8 pylint我建议装在项目的虚拟环境里，而不是全局安装，这样每个项目的规则版本不会互相污染。装好后对单个文件就能直接跑：
flake8 app/models.py pylint app/models.py对一个目录：
flake8 app/ pylint app/第一次跑完大概率会看到一大屏输出。不要慌，这很正常，尤其是老项目。此时的目标不是把数字变成零，而是先看懂它在喊什么。
3.2 读懂输出里的规则编号
以 Flake8 为例，典型输出是"文件路径:行号:列号: 规则码 描述"。比如：
app/models.py:15:1: F401 'os' imported but unused app/models.py:27:5: E501 line too long (92 > 79 characters)规则码第一位字母代表来源：E/W 来自 pycodestyle（E 是错误，W 是警告），F 来自 pyflakes，C 来自 mccabe 复杂度。看到 F401 就知道是"import 了没用"，看到 E501 就是"行太长"。查这些编号非常方便，直接搜"flake8 F401"就能找到官方解释和常见处理方案。
Pylint 的输出格式是"文件路径:行号: 规则码: 描述 (消息名)"，比如：
app/models.py:15:0: C0116: Missing function or method docstring (missing-function-docstring) app/models.py:27:0: R0913: Too many arguments (6/5) (too-many-arguments)规则码同样有意义：C 表示惯例问题（convention），R 表示重构建议（refactor），W 是警告，E 是错误。括号里的消息名是短横线格式，配置时要用这个名字来关闭对应规则。
3.3 退出码和 Pylint 评分：机器怎么判断"过不过"
这里有个容易被忽略但很重要的细节：命令行工具跑完是有退出码的。Flake8 只要发现任何问题就返回非零退出码，所以它天生适合做门禁——CI 里一条命令跑完，非零就挂掉。
Pylint 则用 0 到 10 的评分来表示代码健康度，默认 10 分满分，每发现一个问题按严重程度扣分。CI 里可以用--fail-under=8这种参数来设置分数线，低于 8 分就退出非零。这个机制灵活多了，适合一步步提高标准的场景。
我见过有人为了凑满分把大量规则 disable 掉，这完全本末倒置。评分的意义是给你一个"当前代码整体处于什么水平"的参考，而不是逼你把每个警告都清零。真正健康的做法是设置一条合理基线（比如 8 分），低于它才拦，然后慢慢把分数往上推。
4. 配置才是关键：用 .pylintrc 和 .flake8 定制团队规则
4.1 配置文件从哪来
Flake8 的配置可以放在项目根目录的.flake8文件，也可以是 setup.cfg 里的 [flake8] 段。Pylint 用.pylintrc，一条命令就能生成模板：
pylint --generate-rcfile > .pylintrc生成的模板有几百行注释，第一次看会头晕。我的建议是：不要照单全收，先跑一次默认配置，把那些"明显不合理"的告警记录成清单，然后只针对清单改配置。配置文件的核心作用不是"把所有规则都打开"，而是"把团队认同的规则留下，把不认同的关掉，并写清楚为什么"。
4.2 最值得调整的几个参数
无论 Flake8 还是 Pylint，有几个参数几乎每个项目都要动：行长度上限、函数参数上限、复杂度上限、禁用规则列表。
行长度是争吵最多的一个。PEP 8 建议 79，但现代项目在 120 以内普遍可接受。我不是说越长越好，而是团队用什么格式规范就应该保持一致。Flake8 里写：
[flake8] max-line-length = 120 extend-ignore = E203, W503Pylint 里对应的是：
[MASTER] ignore = migrations, build, venv [MESSAGES CONTROL] disable = C0116, R0903 [DESIGN] max-args = 6 max-complexity = 10E203 和 W503 是 Flake8 里跟 Black 格式化工具冲突的两条规则，用过 Black 的人基本都会把它们加进忽略列表，不然格式化完的代码还会被 Flake8 标红，特别尴尬。
4.3 局部忽略：规则不是一刀切的
配置文件的 disable 是全局的，但实际项目里总有"这个地方我知道违规，但确实合理"的情况。比如一行特别长的 URL、一个动态生成的属性名。这种时候用局部忽略，而不是为了一个角落把整个规则关掉。
Flake8 用# noqa加规则码：
url = "https://example.com/some/very/long/path/that/breaks/line/length" # noqa: E501Pylint 用pylint: disable：
def legacy_api(data): # pylint: disable=too-many-arguments ...# noqa不带规则码的话会忽略这一行所有问题，我建议大家永远带上具体规则码，不然漏掉真正的新问题都不知道。
还有一种更精细的写法，按文件忽略。Flake8 支持per-file-ignores，比如测试文件可以放宽几类规则：
[flake8] per-file-ignores = tests/*:S101整体原则是：局部问题用局部手段解决，全局问题才动全局配置。这条原则在 Pylint 里同样成立，它能按模块、按文件设置不同的禁用项，只是语法稍微绕一点，值得花时间读一遍文档。
5. 接入开发流程：让检查器跑在每个改动落地之前
5.1 为什么先拦住本地
很多人一开始只在 CI 里跑检查，但问题在于：CI 发现错误时代码已经提交了，修复要走一遍完整流程，来回成本高。更聪明的做法是在本地提交之前就拦截。这就是 pre-commit 钩子的价值——commit 命令执行前自动运行一系列检查，不通过就不让提交。
我见过一个项目，早期没有本地拦截，CI 每次都因为一个没删干净的 print 语句挂掉，开发者平均要等三分钟才知道自己错了。后来加了 pre-commit，同样的错在提交瞬间就被拦下来，三分钟变成三秒。
5.2 pre-commit 配置示例
pre-commit 是一个独立的工具，安装后项目根目录放一个.pre-commit-config.yaml：
repos: - repo: https://github.com/PyCQA/flake8 rev: 6.1.0 hooks: - id: flake8 args: ["--config=.flake8"]然后跑一次pre-commit install，之后每次 git commit，它就会先对你的暂存文件做检查。配置里也可以加 Pylint，但因为 Pylint 跑得慢，我一般只把它放到 CI，不太适合放在提交钩子里打断节奏。
5.3 CI 门禁与代码评审的分工
到了 CI 这一层，检查的意义就变了：它不再是"帮你改问题"，而是"确保每个合并进来的代码都满足最低标准"。此时 Pylint 的--fail-under就派上用场，设一条分数线，不达标直接阻止合并。
这种硬门禁的好处是让代码评审从"找低级错误"里解放出来——行太长、没写 docstring、参数太多这类事，机器已经很可靠了，评审人只需要把精力放在逻辑、架构和数据安全上。我常在评审里看到有人给"缺少空行"这类风格问题留评论，说实话这很浪费。把风格问题交给工具，评审才有意义。
5.4 渐进式接入：先管新增代码再清旧债
老项目的存量问题通常几千条，强行清零会让团队崩溃。稳妥做法是只对新代码生效：把旧问题记进一个基线文件，允许存在但不增加。Flake8 和 Pylint 都有类似基线或豁免机制，也可以配合脚本统计增量问题。
这样团队不会有"改一行代码还要顺便修十条老问题"的挫败感，同时新代码的质量从第一天起就被管住。等存量问题慢慢被重构消化，再把基线收紧。我见过一个团队用这种方式，半年后基线文件里的问题从两千多条降到了两百条，中间没有任何一次"集中式大扫除"，全靠每次改动顺手清理。
6. 误报、噪音与规则打架：让团队愿意长期使用的关键
6.1 最常见的误报场景
Pylint 误报率偏高的名声，主要来自几个固定场景。第一个是动态属性，比如 SQLAlchemy 的模型列、Pydantic 的字段，Pylint 静态分析看不到这些运行时才存在的属性，就会报"模块没有 X 成员"。第二个是 pytest 的 fixture 参数，fixture 名字在测试函数里作为参数出现，Pylint 可能报"未定义变量"或"参数未使用"。第三个是框架的全局对象，运行时会注入很多属性，静态分析也不可见。
这类误报一旦出现，记住一个原则：宁可针对具体模块配置豁免，也不要全局关闭相关规则。比如 SQLAlchemy 项目里，可以在 Pylint 配置中写：
[MASTER] ignored-modules = sqlalchemy [DESIGN] generated-members = query, filter, all, firstgenerated-members是告诉 Pylint"这些成员是动态生成的，不用查了"。这个设置比全局 disable 精准得多，不会放过模型里真正的笔误。
6.2 处理误报的正确姿势：先讨论，再忽略
我在团队里推行过一个规矩：任何想增加的 ignore 都必须带注释说明理由。比如测试文件里某个规则被忽略，注释要写出"该文件服务于测试夹具，参数不传默认值是有意的"。这样半年后再有人看到这些豁免，不会一头雾水，不敢删也不敢改。
更重要的次序是：先确认是"工具理解不了业务"还是"代码确实不健康"。有几次我以为是 Pylint 误报，后来仔细一看才发现是自己代码里隐藏了真实问题——一个函数确实参数太多，只是恰好在当前业务里没出事。遇到规则和你直觉冲突时，先读一遍规则文档，再决定是改代码还是豁免规则。大部分时候，改代码是更好的选择。
6.3 降噪三板斧
第一板斧是控制规则范围，别默认全开。Pylint 的 disable 列表可以精简到只剩你真正在乎的规则。第二板斧是分层执行：Flake8 在提交前跑，Pylint 在 CI 跑，别让慢的、严的检查打断高频操作。第三板斧是设定基线而不是清零目标，先让输出数量可视化，看着数字一点点下降，比逼团队一次性清零有效得多。
如果团队刚引入工具，我的建议是前两周只观察，不设硬性门禁，让大家习惯输出格式；第三周开始启用 Flake8 门禁；一个月后再把 Pylint 的分线数纳入合并标准。节奏比力度重要。
6.4 定期复盘规则
规则不是一成不变的。我习惯每个迭代结束后看一眼两份检查报告，删掉那些从没触发过的 disable 项，或者根据新出现的高频告警补充规则。有过一次很典型的经历：项目里所有模块都允许缺少 docstring，后来接口越来越多，新同事对接时经常需要猜函数用途，我们就在复盘里把 C0116 重新打开了，只给公共模块加豁免。
工具的配置会跟着团队的认知一起演化，只要它还在版本控制里，就随时可以安全地调整。把规则当成一个活的东西来维护，而不是装完就再也不碰的静态文件。
7. 几个让我少走弯路的落地习惯
7.1 配置和流程上的三个细节
讲几个工具之外的习惯，这几条才是让整套方案真正发挥价值的点。
第一，配置文件必须进版本库。团队里任何一个人改了配置，其他人通过代码评审就能看到，规则演化全程有记录。第二，只检查改动文件比检查全库更有执行力。git 的暂存机制配合 pre-commit 天然只处理本次改动的文件，这既快又能让"新代码必须干净"这件事变得无路可退。第三，把检查器和格式化工具组合起来用。静态检查负责"指出问题"，格式化工具负责"自动修排版"，两者不重叠但能互相配合。我们项目里约定先格式化再检查，这样 E 类错误基本被消灭，剩下的告警都是真正需要人看的逻辑问题。
7.2 工具之外的一点体会
最后说一点我个人的体会：工具的价值不在于把代码变成零警告的"完美状态"，而在于让团队对"什么算好代码"达成共识。装了 Pylint 和 Flake8 之后，评审里的风格争论几乎消失了，每个人按同一套标准写代码，沟通成本降了一大截。
如果你正在为代码评审里的琐碎争执头疼，不妨先让机器把底线管起来。你会发现，省下来的不只是时间，还有整个团队在细节问题上反复拉扯的耐心。
