VSCode WSL2环境下Python保存时Black自动格式化失效问题

你当前使用的python.formatting.*、python.linting.*系列配置属于VSCode Python扩展的旧版API配置，从2023年发布的新版本开始，Python扩展已将格式化、代码检查能力全部分拆为独立的官方扩展，旧配置在WSL远程场景下不会被识别。这也是为什么Windows本地环境因缓存兼容还能正常运行、WSL端新装的vscode-server既不弹出依赖安装提示、保存时也无任何格式化日志的核心原因。

• 安装WSL端的对应独立扩展
  保持VSCode处于WSL远程连接状态，打开扩展面板，搜索并安装微软官方出品的Black Formatter扩展，注意必须点击扩展卡片上的安装到WSL: Ubuntu-22.04按钮，不能仅安装在Windows宿主机端。如果需要继续使用flake8做代码检查，同理安装官方独立的Flake8扩展即可。
• 替换失效的旧配置
  按Ctrl+Shift+P调出命令面板，输入Preferences: Open Remote Settings (WSL: Ubuntu-22.04)直接打开WSL端的settings.json文件，删除所有python.formatting.*、python.linting.*开头的旧配置，替换为以下内容：

{
  "flake8.args": ["--max-line-length=100", "--ignore=E501"],
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    }
  },
  "black-formatter.args": ["--line-length", "100"]
}

之前配置的python.formatting.blackPath项直接删除即可，WSL远程环境下相对路径解析逻辑和本地终端不一致，手动配置相对路径大概率会定位失败。

• 绑定正确的Python解释器
  再次调出命令面板，输入Python: Select Interpreter，选中当前项目WSL虚拟环境路径下的Python解释器（通常路径为./venv/bin/python），不要选择WSL全局Python或者Windows宿主机的Python解释器。选择完成后Black Formatter扩展会自动从当前选中的解释器环境中检测已安装的black依赖，不需要额外指定可执行文件路径。
• 兜底排查
  完成以上步骤后按Ctrl+Shift+P输入Developer: Reload Window重载窗口，如果还是不生效，按以下方式排查：
  • 打开输出面板，在日志通道下拉列表中选中Black Formatter，查看具体报错信息，如果提示找不到black包，直接在WSL的虚拟环境终端中执行pip install black即可
  • 检查WSL端是否安装了其他Python格式化扩展（如autopep8、yapf），如果有暂时禁用，避免抢占默认格式化器权限
  • 确认没有在工作区配置、文件夹配置中覆盖全局的formatOnSave和defaultFormatter设置

打开任意Python文件，写入几行不符合black格式规范的代码（比如行长度超过100、缩进不规范），按下保存，代码会自动被格式化，同时Black Formatter日志通道会输出对应的执行记录。

内容的提问来源于stack exchange，提问作者Asif Iqbal