VS Code 的 .vscode/settings.json 仅作用于当前工作区，无法按子目录（如 Git 子模块）自动切换 Black 格式化参数；需通过多根工作区或项目级配置（如 pyproject.toml）实现真正的差异化设置。
vs code 的 `.vscode/settings.json` 仅作用于当前工作区，无法按子目录（如 git 子模块）自动切换 black 格式化参数；需通过多根工作区或项目级配置（如 `pyproject.toml`）实现真正的差异化设置。
在大型 Python 项目中，主仓库与子模块可能遵循不同的代码风格规范（例如行宽限制：主仓库和 sub_01 要求 --line-length=150，而 sub_02 严格限定为 100）。你尝试在各目录下分别配置 .vscode/settings.json，但发现 VS Code 始终采用主工作区的设置（如 150），这是因为 VS Code 的用户/工作区设置不具备路径感知的“嵌套覆盖”能力——它不会根据当前编辑文件的物理路径动态加载对应子目录下的 settings.json。
✅ 正确解决方案如下：
✅ 方案一：使用 pyproject.toml（推荐，符合 Black 官方最佳实践）
Black 自 v22.1.0 起原生支持基于项目根目录的 pyproject.toml 配置，且会自动向上查找最近的配置文件。你只需为每个子模块（及主仓库）各自维护独立的 pyproject.toml：
# main_repo/pyproject.toml [tool.black] line-length = 150
# main_repo/subs/sub_01/pyproject.toml [tool.black] line-length = 150
# main_repo/subs/sub_02/pyproject.toml [tool.black] line-length = 100
✅ VS Code 的
ms-python.black-formatter扩展会自动识别并应用当前文件所在目录的pyproject.toml配置（无需额外设置），真正实现“按路径生效”。
✅ 方案二：启用多根工作区（Multi-root Workspace）
将主仓库与各子模块作为独立文件夹添加到一个 .code-workspace 文件中，每个文件夹可拥有专属 settings.json：
// main_repo.code-workspace
{
"folders": [
{ "path": "." },
{ "path": "subs/sub_01" },
{ "path": "subs/sub_02" }
],
"settings": {
"[python]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "ms-python.black-formatter"
}
}
}
然后在 subs/sub_02/.vscode/settings.json 中单独指定：
{
"black-formatter.args": ["--line-length=100"]
}
⚠️ 注意：此方式需手动打开 .code-workspace 文件（而非单纯打开 main_repo/ 文件夹），否则子模块设置不生效。
❌ 不可行方案说明
- 单一工作区下的多层
.vscode/settings.json会被合并（非覆盖），且 VS Code 总是优先采用最外层（主目录）的black-formatter.args，无法按路径区分（参见 VS Code Issue #32693 —— 该功能目前仍为“已提出但未实现”状态）。
? 总结：永远优先使用 pyproject.toml 进行 Black 配置。它跨编辑器、跨 CI/CD 一致，且天然支持子模块隔离；.vscode/settings.json 仅应作为 IDE 特定行为（如保存触发时机）的补充，而非核心格式规则的载体。
