VS Code 的 .vscode/settings.json 文件作用域仅限于当前工作区根目录，无法按子目录（如子模块）自动切换 Black 配置；需改用项目级配置文件（如 pyproject.toml）实现真正隔离的格式化规则。
vs code 的 `.vscode/settings.json` 文件作用域仅限于当前工作区根目录，无法按子目录（如子模块）自动切换 black 配置；需改用项目级配置文件（如 `pyproject.toml`）实现真正隔离的格式化规则。
在多子模块 Python 项目中，期望为每个子模块（如 subs/sub_01 和 subs/sub_02）应用不同的 Black 行宽（例如 --line-length=150 vs --line-length=100），仅靠 VS Code 的多层 .vscode/settings.json 是无效的——因为 VS Code 不支持基于文件路径动态加载不同工作区设置，所有打开的文件默认继承主工作区（即 main_repo/ 根目录）的 .vscode/settings.json，子目录下的同名设置文件会被忽略。
✅ 正确做法：使用 层级化 pyproject.toml 配置
Black（v22.3.0+）、Flake8 等主流工具均原生支持“就近读取”配置：它们会从当前文件所在路径向上查找最近的 pyproject.toml（或 pyproject.toml、setup.cfg 等），并以该配置为准。因此，你应在每个需要差异化配置的目录下放置独立的 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 的 Black 扩展（如 ms-python.black-formatter）已启用「自动检测配置」（默认开启），并在主工作区的 .vscode/settings.json 中移除硬编码的 black-formatter.args，仅保留基础行为声明：
{
"[python]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "ms-python.black-formatter"
}
}⚠️ 注意事项：
- 不要混用
black-formatter.args和pyproject.toml：命令行参数会覆盖配置文件，导致子模块配置失效； - 确保子模块目录是 Git 子模块且已正确检出（
git submodule update --init），否则 VS Code 可能无法识别其为有效 Python 项目上下文； - 若使用 Pylance 或其他语言服务器，建议也在各
pyproject.toml中统一指定requires-python或dependencies，增强环境感知一致性。
总结：VS Code 的设置文件不具备路径感知能力，真正的配置隔离必须依赖工具链自身的分层配置机制（如 pyproject.toml）。这是跨编辑器（PyCharm、Vim + coc.nvim 等）通用的最佳实践，也符合 PEP 518 标准。
