pycharm可通过配置“actions on save”或“file watchers”实现保存时自动格式化：前者直接勾选“reformat code”，后者需安装black并配置监听器，确保其路径在系统path中或显式指定绝对路径，同时合理排除migrations、proto等无需格式化的文件。
PyCharm 本身不内置 Black 或 Yapf，但能通过外部工具集成实现保存时自动格式化——关键在于正确配置“External Tools”和“On Save”触发逻辑，否则会静默失败或报 File not found 错误。
确认 Black/Yapf 已全局可用（非仅虚拟环境）
PyCharm 的外部工具默认使用系统 PATH 查找命令，若只在项目虚拟环境中安装 black 或 yapf，PyCharm 很可能找不到可执行文件：
- 终端中运行
which black（macOS/Linux）或where black（Windows），确保路径能被 PyCharm 读取； - 如果只在 venv 中安装，要么把 venv 的
bin/（或Scripts\）加进系统 PATH，要么在 PyCharm 中显式指定完整路径，例如：/Users/you/project/.venv/bin/black； - 验证方式：在 PyCharm 终端里直接运行
black --version，成功才继续下一步。
在 External Tools 中添加 Black/Yapf 命令
这一步定义「调用什么命令、传什么参数」，必须匹配工具实际接受的语法：
- 菜单进入
Settings > Tools > External Tools，点击+添加； -
Name填Black或Yapf； -
Program填绝对路径（如/usr/local/bin/black）； -
Arguments推荐用：--line-length=88 --skip-string-normalization $FilePath$（Black）或-i -p $FilePath$（Yapf）； -
Working directory设为$ProjectFileDir$，避免路径解析错误； - 勾选
Show console when a tool is run，便于调试报错。
绑定到 “On Save” 并排除不需要格式化的文件
自动格式化不是越激进越好——比如 __init__.py 被清空、生成的 pb2.py 被重排，都会引发运行时问题：
- 进入
Settings > Tools > Actions on Save； - 勾选
Run external tool，并从下拉菜单选择刚建好的Black； - 务必点击
Configure...，在弹窗中设置Scope为Files matching pattern，填入：*.py； - 再点
Exclude，添加常见不应格式化的路径模式，例如：**/migrations/*.py、**/proto/*.py、**/__pycache__/**； - 注意：PyCharm 2023.2+ 支持对单个文件类型启用不同 formatter，但 Black/Yapf 不支持 per-file 配置，所以靠路径排除更可靠。
验证与常见失败原因
改完设置后，打开一个含缩进混乱的 .py 文件，手动保存，观察是否生效：
- 若无反应，检查 External Tools 的
Working directory是否写成$FileDir$（错误）——应为$ProjectFileDir$； - 若报错
black: error: unrecognized arguments: --skip-string-normalization，说明 Black 版本太旧（pip install -U black； - 若格式化后代码变“更丑”，比如字符串被强制换行，可能是
--line-length和项目已有风格冲突，建议先统一团队配置，再同步进 PyCharm； - Yapf 默认不兼容 PEP 8 的某些约定（如多行 import 分组），需额外加
--style=pep8参数才能接近 Black 行为。
真正卡住人的往往不是怎么配，而是没意识到 PyCharm 的 External Tools 对路径、权限、Python 环境隔离极其敏感——哪怕 black 在终端能跑，PyCharm 也可能因 shell 启动方式不同而找不到它。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
