Black在VSCode中不自动格式化Python，根本原因是Python解释器路径、python.formatting.provider设置、pyproject.toml文件位置及[tool.black]段三者未同时满足；缺一不可。
Black 在 VSCode 里不自动格式化 Python，基本就是三件事没对齐：Python 解释器路径、python.formatting.provider 设置、pyproject.toml 文件位置和内容——缺一不可。
Python 解释器路径必须和 black 安装环境一致
VSCode 不会跨环境找black，它只在你当前选中的 python.defaultInterpreter 对应的环境里执行 python -m black。
终端里能跑 black --version，不代表 VSCode 能用。
- 按
Ctrl+Shift+P（Mac 为Cmd+Shift+P），运行Python: Select Interpreter，确认路径指向你装了black的环境（如./venv/bin/python或~/miniconda3/envs/myenv/bin/python） - 在 VSCode 集成终端里运行
python -m black --version；若报ModuleNotFoundError: No module named 'black'，说明没装对，立刻在这个环境下重装：pip install black - 用 conda 的话，别只在
base环境装black，必须先conda activate myenv再pip install black
python.formatting.provider 必须显式设为 black
VSCode 默认不设这个字段，也不会 fallback 到 black，哪怕你装了插件或命令行能用。
- 打开
Preferences: Open Settings (JSON)，加这三行（注意方括号和引号）："python.formatting.provider": "black""editor.formatOnSave": true"[python]": { "editor.formatOnSave": true } - 删掉
python.formatting.blackArgs这类冗余配置——除非你真要传额外参数（比如--skip-string-normalization），否则它大概率被忽略，还容易拼错成python.formatting.blackargs（小写 a）导致静默失效 - 别写成
python.formatting.blackProvider或python.formatting.defaultProvider，只有python.formatting.provider是有效键名
pyproject.toml 必须在项目根目录且含 [tool.black]
VSCode 的 Python 扩展只认工作区根目录下的 pyproject.toml，且必须包含合法的 [tool.black] 段。写成 .black、black.toml、或放在 src/ 里，它直接无视。
- 文件名只能是
pyproject.toml，不能是setup.cfg或tox.ini（Black 22.3.0+ 已弃用） - 必须放在 VSCode 左上角显示的工作区根目录，不是子目录
- 最小可用配置示例（存为项目根目录下的
pyproject.toml）：[tool.black] line-length = 88 skip-string-normalization = true include = '\.pyi?$' exclude = ''' /(\.git|__pycache__|venv)/ '''
- 改完配置后，必须执行
Ctrl+Shift+P→Developer: Reload Window，否则旧缓存会让新规则不生效
格式化行为和命令行不一致？优先级和作用域是关键
Black 本身读取配置的顺序是：命令行参数 >pyproject.toml > 其他旧格式配置文件。而 VSCode 的 python.formatting.blackArgs 只能传额外参数，**不能覆盖 pyproject.toml 里的 [tool.black] 配置**——这点非常容易被忽略。
- 如果你的
pyproject.toml里写了line-length = 100，但 VSCode 设置里写了"python.formatting.blackArgs": ["--line-length", "88"]，后者会被无视 - 常见冲突点：
skip-string-normalization、preview、include/exclude正则——这些都得统一在pyproject.toml里配才可靠 - 调试方法：在终端里手动跑
black --diff your_file.py，看输出是否和 VSCode 里一致；不一致就说明 VSCode 没走对环境或配置
改完所有配置后，最容易被跳过的一步是重载窗口——不点 Developer: Reload Window，VSCode 很可能还在用旧缓存。
