在实际 Python 项目里静态代码审查器并不少见但 Scrut 的设计角度比较特别它把注意力放在 Git 变更过的文件上。传统做法是每次提交前对全量代码跑一遍 pylint、flake8 或 mypy这种方式在项目变大之后会越来越慢也会让提交者被历史遗留告警淹没。Scrut 这类工具尝试回答一个更实际的问题这次改动有没有引入新问题。它会先读取 Git 仓库里本次提交或工作区变更涉及的文件再对这批文件执行静态检查从而让代码审查从“全量巡检”变成“增量守卫”。这篇文章会基于这个思路从概念、环境、实现、CI 集成、排错和最佳实践几个角度带你把一个类似 Scrut 的 Python 静态代码审查小工具完整落地。学完后你可以把它接入个人项目也可以在此基础上扩展成团队统一的质量门禁。1. 先理解为什么要对 Git 变更文件做增量静态检查1.1 全量扫描的问题在哪里很多团队最初引入静态检查时都会直接用pylint src/或flake8 .这样的全量命令。项目规模小时这套方法简单直接项目规模变大后问题会逐渐暴露。第一是耗时。一个稍大的 Python 仓库可能有几千个文件全量跑一次 flake8 或 pylint 可能需要几十秒到几分钟。如果在每个 commit 或 PR 里都这样跑CI 时间会被明显拉长。第二是历史噪音。仓库里往往存在大量历史遗留告警比如老代码里的未使用变量、未定义名字、过时接口。新提交者看到满屏报错时很难判断哪些问题是自己这次改动引入的。于是“检查工具”慢慢变成了“没人认真看的红绿灯”。第三是审查效率。代码评审真正关心的是增量逻辑也就是这次变更带来的新风险。全量报告里混着旧问题和历史债评审者需要额外花时间做筛选。Scrut 这类工具的价值就是把检查范围收窄到 Git 变更文件。它不替代全量扫描而是把增量检查变成提交前和 PR 阶段的第一道防线。1.2 Scrut 的核心链路变更文件加静态检查器从项目名称和定位可以提炼出它的核心链路一共四步通过 Git 命令获取变更文件列表。过滤出需要检查的 Python 文件。对每个文件执行静态检查器例如 pyflakes、flake8 或 pylint。汇总结果并控制进程退出码。这条链路的关键在第一步。只要变更文件获取准确后续静态检查就可以复用成熟的现成工具。Scrut 这类工具本身并不需要重新实现语法分析它更擅长“范围控制”和“流程编排”。变更文件通常包含三类已跟踪文件的工作区修改。已暂存到索引但尚未提交的修改。Git 尚未跟踪的新文件。不同场景需要不同处理方式后面实现部分会逐个说明。1.3 适用场景和不适用场景增量静态检查并不是银弹它适合的典型场景是PR / MR 审查只检查本次分支与目标分支的差异文件。pre-commit 钩子提交前只检查暂存区涉及的文件。大型历史项目不想被存量告警困扰只想守住新增代码质量。团队规范试行期先让新改动符合规范再逐步清理历史债。不适合的场景也很明显定期全量巡检。历史债务专项治理。对第三方依赖目录或生成代码做整体安全扫描。所以增量检查更适合做“质量门禁”全量检查更适合做“健康报告”。两者应该共存而不是互相替代。2. 环境准备与前置依赖2.1 基础环境要求实现一个类似 Scrut 的工具并不需要复杂环境。建议准备以下基础环境工具用途最低要求Git获取变更文件、计算 diffGit 2.x 以上Python运行脚本和静态检查器Python 3.8 以上pyflakes示例用静态检查器最新稳定版即可flake8 / pylint可选的扩展检查器按需安装这里推荐 Python 3.8 以上因为脚本中会用到subprocess.run的text参数、capture_output等特性。如果要在 Windows 上运行还需要留意编码问题后面排错部分会讲到。先确认本机环境python --version git --version pip --version如果命令不存在需要先安装对应工具。不同操作系统的安装方式差异较大这里不展开核心原则是保证python、pip、git三类命令都可用。2.2 安装静态检查依赖最小复用方案只需要 pyflakes。pyflakes 的特点是快、足够轻量它不会检查代码风格只检查语法错误和逻辑问题比如未定义名字、未使用的导入、重复导入等。安装命令pip install pyflakes如果想同时支持 flake8 或 pylint可以一并安装pip install pyflakes flake8 pylint在真实项目中建议把依赖写进requirements.txt或pyproject.toml避免 CI 和本地环境版本不一致。这里示例只做演示所以直接安装即可。2.3 准备一个可测试的 Git 仓库为了验证后面的工具先准备一个小仓库。先初始化仓库并创建一个正常文件mkdir demo-scrut cd demo-scrut git init -b main cat main.py EOF def main(): return demo if __name__ __main__: main() EOF git add main.py git commit -m initial接着创建一个包含问题的文件并加入暂存区cat utils.py EOF def unused(): missing_name EOF git add utils.py这个文件里故意写了一个不存在的名字missing_name。pyflakes 会报出undefined name错误。这样后面运行工具时能够看到清晰的问题输出。要检查未暂存的工作区修改可以继续修改main.py但不加入暂存区。后续工具默认会对比工作区与HEAD因此两种修改都能覆盖到。3. 实现一个类似 Scrut 的最小工具3.1 项目结构最小工具只需要一个 Python 文件也可以按模块拆开。本文用一个文件演示方便直接保存运行demo-scrut/ ├── main.py ├── utils.py ├── requirements.txt └── scrut_reviewer.py其中scrut_reviewer.py是核心脚本。它承担三类职责获取 Git 变更文件、调用静态检查器、输出报告并设置退出码。3.2 获取变更文件Git diff 与 ls-files 的配合先实现获取变更文件的函数。这里使用git diff --name-only --diff-filterACMRT并且加-z参数处理文件名中的空格、中文和换行。import subprocess def run_command(cmd): return subprocess.run( cmd, capture_outputTrue, textTrue, encodingutf-8, errorsreplace, checkFalse, ) def get_changed_files(base, staged, include_untracked): git_diff [git, diff, --name-only, -z, --diff-filterACMRT] if staged: git_diff.append(--cached) git_diff.append(base) result run_command(git_diff) if result.returncode ! 0: raise SystemExit(fgit diff 执行失败{result.stderr.strip()}) paths [p for p in result.stdout.split(\0) if p] if include_untracked: untracked run_command( [git, ls-files, --others, --exclude-standard, -z] ) if untracked.returncode 0: paths.extend(p for p in untracked.stdout.split(\0) if p) return paths关键点有三个-z让 Git 使用 NUL 字符分隔文件名而不是换行。这样即使文件名里包含空格或中文也不会被错误拆分。--diff-filterACMRT表示只保留新增A、复制C、修改M、重命名R、类型变化T的文件。删除文件不在检查范围内因为静态检查无法读取已删除文件的内容。默认git diff不包含未跟踪文件所以需要额外调用git ls-files --others --exclude-standard获取新文件。3.3 调用检查器通过 subprocess 复用 pyflakes获取文件列表后需要过滤出 Python 文件再调用静态检查器。from pathlib import Path def filter_python_files(paths, pattern): if not pattern: return [Path(p) for p in paths] return [Path(p) for p in paths if Path(p).match(pattern)] def run_linter(paths, linter): if not paths: return , 0 if linter pyflakes: cmd [sys.executable, -m, pyflakes] elif linter flake8: cmd [sys.executable, -m, flake8] else: cmd [sys.executable, -m, pylint, --scoreno] cmd.extend(str(p) for p in paths) result run_command(cmd) report result.stdout if result.stderr: report result.stderr return report, result.returncode这里使用sys.executable而不是直接写python可以确保脚本调用的是当前 Python 解释器避免虚拟环境与系统 Python 不一致的问题。pyflakes 的返回码语义是有静态检查问题返回非 0没有问题返回 0。flake8 和 pylint 也类似。所以可以直接把 linter 的返回码作为工具是否发现问题的判断依据。3.4 组合 CLI 入口最后设计命令行入口。使用 Python 标准库的argparse不引入额外依赖。import argparse import sys def main(): parser argparse.ArgumentParser( descriptionA mini static reviewer for changed Git Python files. ) parser.add_argument(--base, defaultHEAD, help对比基准默认 HEAD) parser.add_argument(--staged, actionstore_true, help只检查已暂存变更) parser.add_argument( --include-untracked, actionstore_true, help同时检查未跟踪文件, ) parser.add_argument(--pattern, default*.py, help文件匹配规则默认 *.py) parser.add_argument( --linter, defaultpyflakes, choices[pyflakes, flake8, pylint], help选择静态检查器, ) parser.add_argument( --fail-on-issues, actionstore_true, help发现告警时退出码为 1, ) args parser.parse_args() changed get_changed_files(args.base, args.staged, args.include_untracked) target_files filter_python_files(changed, args.pattern) target_files [p for p in target_files if p.exists()] report, code run_linter(target_files, args.linter) if report.strip(): print(report.rstrip()) print(f\n检查文件数{len(target_files)}) if code ! 0: print(发现静态检查问题。) if args.fail_on_issues: sys.exit(1) else: print(未发现静态检查问题。)注意target_files [p for p in target_files if p.exists()]这一步。因为 Git 记录中可能出现重命名、删除或类型变化某些路径在磁盘上已经不存在静态检查器无法读取它们需要主动过滤。组合完整代码后运行python scrut_reviewer.py --base HEAD --staged预期输出类似于utils.py:1:6: undefined name missing_name 检查文件数1 发现静态检查问题。如果希望发现问题时让退出码为 1可以追加python scrut_reviewer.py --base HEAD --staged --fail-on-issues echo $?这会输出1方便接入 CI。4. 关键参数与配置细节4.1 主要参数速查参数默认值作用典型使用场景--baseHEAD指定 Git 对比基准本地用 HEADCI 用目标分支--staged关闭只检查已暂存变更pre-commit 钩子--include-untracked关闭把未跟踪文件纳入检查新文件尚未 git add 时的本地检查--pattern*.py文件匹配规则只检查 src 目录或测试代码--linterpyflakes选择静态检查器团队统一用 flake8 或 pylint--fail-on-issues关闭发现问题时退出码为 1CI 质量门禁4.2 对比基准的选择--base是最容易出错的地方。HEAD表示当前提交如果你有多个未提交的修改直接对比工作区和HEAD能覆盖所有未提交变更。在 CI 环境通常需要对比“目标分支最新提交”和“当前分支最新提交”。GitHub Actions 里可以传github.event.pull_request.base.shaGitLab CI 里可以传CI_MERGE_REQUEST_DIFF_BASE_SHA。没有准确基准时git diff的结果会为空或错误。4.3 已暂存、未暂存与未跟踪文件不少初学者会混淆git status里的三类状态未暂存修改文件已经修改但没有git add。已暂存修改文件已经git add进入索引。未跟踪文件从来没有加入过 Git 版本控制。git diff --name-only默认对比工作区与索引所以主要展示“未暂存修改”。加上--cached后展示的是“已暂存修改”。如果直接对比某个 commit展示的是工作区相对于该 commit 的所有变更。为了符合直觉本文脚本在未加--staged时直接将 base 作为另一侧相当于git diff HEAD会把已暂存和未暂存都算进来。这样更符合“检查当前所有改动”的预期。4.4 删除文件必须排除静态检查器只能读取磁盘上存在的文件。git diff返回的删除文件没有内容因此需要处理。本文使用两个层面的过滤--diff-filterACMRT排除 D 状态。p.exists()二次确认文件真实存在。两步过滤可以避免某些极端情况比如文件被重命名后旧路径不存在、新路径存在Git 仍可能返回两个路径。5. 接入 CI 做成质量门禁5.1 GitHub Actions 配置示例把增量静态检查放进 PR 流程最常用的是 GitHub Actions。示例配置如下name: review-changed-python on: pull_request: push: branches: - main jobs: scrutinize: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 with: fetch-depth: 0 - name: Setup Python uses: actions/setup-pythonv5 with: python-version: 3.12 - name: Install dependencies run: pip install pyflakes flake8 pylint - name: Run incremental review run: | python scrut_reviewer.py \ --base ${{ github.event.pull_request.base.sha }} \ --include-untracked \ --linter pyflakes \ --fail-on-issues这里使用fetch-depth: 0是为了让 CI 能拿到完整的 Git 历史避免因为浅克隆导致pull_request.base.sha不存在。如果仓库改动频繁也可以只获取到指定深度但要确保 base 提交存在。5.2 GitLab CI 配置示例GitLab CI 的配置思路类似static-review: image: python:3.12 before_script: - git config --global --add safe.directory $CI_PROJECT_DIR - pip install pyflakes flake8 pylint script: - python scrut_reviewer.py --base ${CI_MERGE_REQUEST_DIFF_BASE_SHA:-origin/main} --include-untracked --linter pyflakes --fail-on-issuesGitLab CI 中CI_MERGE_REQUEST_DIFF_BASE_SHA是合并请求的 diff 基准提交优先级最高。如果变量不存在则用origin/main作为兜底。这里还加了safe.directory配置解决部分 CI 容器中detected dubious ownership in repository的问题。5.3 CI 中的预期验证结果接入 CI 后执行结果会出现在流水线日志中。在正常无告警时会看到检查文件数3 未发现静态检查问题。如果存在告警脚本会在日志中打印具体文件行号并因为--fail-on-issues返回退出码 1CI 任务随之失败。注意CI 失败是预期行为而不是“工具出 bug”。只有让有问题的改动无法通过检查才能让增量检查真正成为质量门禁。6. 常见问题与排查路径6.1 变更文件始终为空现象脚本输出“检查文件数0”但明明修改了 Python 文件。可能原因--staged开启但文件没有git add。--base指向的提交不存在比如浅克隆仓库。修改的是非 Python 文件被--pattern过滤。修改了未跟踪文件但没有开启--include-untracked。检查方式git status git diff --name-only HEAD git diff --name-only --cached HEAD git ls-files --others --exclude-standard处理建议先手动运行一遍 Git 命令确认文件列表再确认脚本参数。尤其注意--staged和--include-untracked的组合。6.2 文件名包含中文或空格时解析错误现象脚本把我的 file.py拆成了我的和file.py静态检查报错找不到对应文件。原因早期版本的命令用split()或按换行拆分文件名遇到空格就会出错。Git 默认输出文件名时也可能用引号包裹特殊字符。解决方案是统一使用-z参数并让 Python 按\0拆分。这也解释了为什么本文脚本从一开始就使用stdout.split(\0)。如果 Git 输出中文文件名为转义形式可以先执行git config --global core.quotepath false这样 Git 会直接输出原始 UTF-8 文件名便于调试。6.3 已删除文件仍然被检查现象脚本报错说某个.py文件不存在而这个文件其实已经删除或重命名。原因git diff可能返回重命名或删除路径静态检查器无法读取不存在的内容。检查方式git diff --name-status HEAD处理建议在获取文件列表时使用--diff-filterACMRT同时在过滤后加p.exists()。如果仍然出现问题可以把文件路径打印出来人工核对实际状态。6.4 本机能跑CI 上跑不了现象本地运行正常CI 中报dubious ownership、no such base、ModuleNotFoundError。这类问题最常见的是环境差异。现象可能原因处理建议detected dubious ownershipGit 认为仓库所有者不可信CI 前执行git config --global --add safe.directory $CI_PROJECT_DIRfatal: bad object浅克隆没有 base 提交checkout 时设置fetch-depth: 0或传入正确的 base SHAModuleNotFoundError: No module named pyflakeslinter 没有安装固定 requirements并在脚本步骤前安装中文文件名乱码CI 区域设置与本地不同在脚本中显式传encodingutf-8并设置core.quotepath false处理顺序建议是先看 Git 命令是否能跑通再看 linter 是否安装最后看脚本参数和退出码是否符合预期。7. 最佳实践与扩展方向7.1 从学习环境到生产环境本文脚本适合学习和本地验证。生产环境使用时还需要补齐以下能力固定依赖版本避免 pyflakes 或 flake8 升级后行为变化。把报告写入日志文件或上传到 CI 产物方便评审者查看。设置合理的超时时间防止某个超大文件导致 linter 一直运行。在 CI 中使用独立账号执行不暴露写权限。对大量历史仓库先用“非阻塞模式”跑一段时间再切换成阻断式检查。支持多个 Python 版本矩阵避免某个版本特有的语法误报。7.2 可复用检查清单每次接入增量静态检查时可以参考以下清单检查项确认点基准提交本地用 HEADCI 用目标分支 base SHA文件列表确认git diff返回的文件包含本次所有改动未跟踪文件新文件是否纳入检查删除文件是否被--diff-filter和p.exists()排除文件名安全是否使用-z解析路径linter 版本本地和 CI 是否一致退出码有问题时是否返回非 0报告输出评审者能否直接看到文件、行号和告警信息全量扫描是否另行安排历史债务巡检7.3 扩展方向这个最小工具可以继续扩展。比较有价值的几个方向如下。第一支持 ruff。ruff 速度很快而且同时覆盖 lint 和 format 检查。可以先检查 ruff 是否可用如果团队已经引入 ruff把--linter扩展成 ruff 并不难。第二把结果结构化成 JSON。比如记录每个文件的告警列表、严重级别、行号、规则名。结构化的报告可以接入自定义页面或评审机器人。第三从文件级增量升级到行级增量。文件级检查仍然会把旧告警一起带出来。更精细的做法是先读取 diff 的 patch只对新增或修改的行执行规则过滤例如只检查新增行是否包含print、是否缺少异常处理等。第四做成 pre-commit hook。在.pre-commit-config.yaml中注册脚本让开发者在本地提交前就收到反馈。第五加入缓存。用 Git blob 的哈希作为缓存键只有文件内容发生变化时才重新检查可以进一步缩短重复运行时间。增量静态检查真正的价值不是替代全量扫描而是把质量检查前移到每一次改动刚发生的时候。理解 Git 变更文件获取方式理解 linter 的退出码和输出格式再把它接入 CI一个类似 Scrut 的小工具就能成为团队代码质量基础设施的一部分。