Black负责无条件格式化，Flake8负责逻辑与风格质检，两者不替代、不分主次——但必须用pre-commit钩子强制落地，否则在Web团队中90%的配置会失效；需在.flake8或pyproject.toml中ignore = ["E203", "W503"]以解决Black与Flake8规则冲突，且pre-commit中black hook必须排在flake8前。
直接上结论：Black负责无条件格式化，Flake8负责逻辑与风格质检，两者不替代、不分主次——但必须用pre-commit钩子强制落地，否则在Web团队中90%的配置会失效。
Black格式化后为什么Flake8还报E203/W503？
这是Web团队最常卡住的第一步。Black默认把二元运算符（如+、==）放在行尾，而旧版Flake8的E203（冒号/逗号前空格）和W503（运算符换行）规则会把它当错误报出来。
- 必须在
.flake8或pyproject.toml里显式忽略：ignore = E203, W503 - 不能只靠
flake8-black插件——它只校验是否符合Black输出，不覆盖Flake8原有规则 - 如果用
pyproject.toml，写法是：[tool.flake8] ignore = ["E203", "W503"] - 漏掉这点，
pre-commit会立刻失败，新人提交代码直接被拦住
Web项目里哪些文件不该被Black碰？
不是所有.py文件都适合Black一锅端。尤其在Flask/Django/FastAPI项目中，以下三类文件手动保留原始格式更安全：
-
migrations/下的数据库迁移脚本：Black可能重排operations顺序，导致迁移执行异常 - 带特殊字符串拼接的模板渲染逻辑（如Jinja2内联Python）：Black对三引号字符串的括号续行处理可能破坏渲染逻辑
- 硬编码的API响应结构（如
json.dumps(..., indent=2)生成的字典）：Black会打散缩进，反而让diff难以追踪真实变更
统一做法是在pyproject.toml里用exclude字段排除：exclude = ['migrations/', 'tests/fixtures/', 'scripts/deploy.py']。
立即学习“Python免费学习笔记（深入）”；
Flake8检查时发现大量F401（未使用导入），但代码明明用了？
这通常发生在Web框架的动态导入场景：比如Flask的@app.route装饰器、Django的admin.site.register()、FastAPI的@router.get——这些导入只在运行时被框架扫描，静态分析器看不到调用链。
- 不要盲目加
# noqa: F401，先确认是不是import写在了函数内部（Flake8无法跨作用域追踪） - 更稳妥的做法是用
isort配合Black：在pyproject.toml里启用[tool.isort] profile = "black"，让导入分组和排序与Black兼容 - 若仍存在误报，针对性忽略：
per-file-ignores = "app.py:F401"，而不是全局关掉 - CI里跑
flake8 --select=F401单独验证，避免掩盖真问题
pre-commit配置里Black和Flake8的执行顺序重要吗？
重要，且顺序错了会导致CI通过但本地提交失败。
- 必须先
black再flake8：因为Black改完格式后，Flake8才做最终校验 - 在
.pre-commit-config.yaml中，blackhook要排在flake8前面，否则hook会拿未格式化的代码去检查 - 别用
flake8-black插件代替独立hook——它只做风格校验，不触发实际格式化，开发时看不到效果 - 加个
args: [--check]到Black hook里，确保pre-commit阶段不改文件，只报错；真正格式化留给IDE或手动black .
Web团队最容易忽略的是：不同成员本地编辑器自动保存时是否启用了Black格式化。VS Code需装Python扩展并设"python.formatting.provider": "black"，PyCharm要在Settings → Tools → Python Integrated Tools里选Black——没对齐，pre-commit就变成“惩罚工具”而非“协作保障”。
