VS Code .code-workspace 配置指南：Python / C/C++ 嵌入式开发

基于 STM32F407 ARM GCC + clangd + Python 项目的实战配置文档

目录

  1. 什么是 .code-workspace 文件
  2. 文件基础结构
  3. 布局与外观
  4. 侧边栏、面板与编辑器布局
  5. 编辑器外观与行为
  6. 代码编辑优化
  7. C/C++ 专项配置（clangd）
  8. Python 专项配置
  9. 其他语言专项配置
  10. 文件排除与搜索排除
  11. 终端与调试
  12. Build Tasks（CMake + Ninja）
  13. 附：完整可复用模板

1. 什么是 .code-workspace 文件

.code-workspace 是 VS Code 的多根工作区配置文件，相比 .vscode/settings.json 有以下优势：

特性.vscode/settings.json.code-workspace
作用范围仅当前项目可跨多个项目文件夹聚合
共享方式随项目提交 Git独立文件，可放在任意位置
多文件夹不支持支持 "folders": [...]
推荐启动方式code .code xxx.code-workspace

最佳实践：将有硬件依赖的 C/C++ 项目（如 STM32 HAL 库在外置目录）通过 folders 聚合到同一个工作区，同时统一所有编辑器行为。

下图展示了 .code-workspace 如何将多个项目文件夹聚合到统一的工作区：

code my_project.code-workspace

加载 .code-workspace 文件

folders 聚合多个项目

STM32 固件工程

Python 上位机

共享脚本/工具

settings 统一配置

编辑器外观与行为

C/C++ clangd 配置

Python Black 格式化

tasks 自动化任务

CMake 配置/编译/清理

2. 文件基础结构

{
  // ===== ① 工作区包含哪些文件夹 =====
  "folders": [
    { "path": "." }, // 当前目录；可写多个路径
  ],

  // ===== ② 全局 Settings（会继承到所有文件夹） =====
  "settings": {
    // ... 各种配置项 ...
  },

  // ===== ③ 自动化 Tasks（编译、清理等） =====
  "tasks": {
    "version": "2.0.0",
    "tasks": [
      /* ... */
    ],
  },
}

注意：VS Code 工作区只认 settings、folders、launch、tasks、extensions 这几个顶层键。JSON 标准不允许注释，但 VS Code 使用 jsonc 模式时注释可见。

3. 布局与外观

// ====================== 布局与外观 ======================
"workbench.colorTheme": "GNOME2-like",            // 颜色主题
"workbench.iconTheme": "vs-seti",                 // 文件图标主题
"workbench.productIconTheme": "emoji-product-icons", // IDE 内部图标风格
"workbench.editor.empty.hint": "hidden",          // 隐藏空编辑器的大 Logo 提示
"workbench.startupEditor": "none",                // 启动时不打开上次的文件
"workbench.editor.showTabs": "multiple",          // 允许多标签页
"workbench.tree.renderIndentGuides": "always",    // 文件浏览器缩进引导线

常用配色推荐

主题名称风格适合场景
Nord冷色调、低对比度长时间编码
Nord Wave暖色变体夜间使用
GitHub Dark Dimmed柔和深色GitHub 用户首选
GNOME2-like经典 GNOME 配色怀旧 Linux 风格

4. 侧边栏、面板与编辑器布局

// ====================== 侧边栏与面板 ======================
"workbench.sideBar.location": "left",           // 侧边栏靠左
"workbench.panel.defaultLocation": "bottom",    // 终端面板在底部
"workbench.statusBar.visible": true,            // 显示底部状态栏

// ====================== 编辑器布局 ======================
"workbench.editor.splitOnDragAndDrop": true,    // 拖文件到边缘 → 自动分屏
"workbench.editor.enablePreview": false,        // 单击直接打开（不覆盖当前标签）
"workbench.editor.limit.enabled": true,         // 限制打开标签数
"workbench.editor.limit.perEditorGroup": true,  // 每组编辑器最多 5 个标签

// ====================== 快速访问 ======================
"workbench.quickOpen.closeOnFocusLost": true,   // 失焦时关闭快速搜索
"workbench.commandPalette.preserveInput": true, // 保留命令面板历史输入

enablePreview: false 非常重要：默认 VS Code 单击文件以「预览模式」打开，再点另一个文件就会覆盖。设为 false 后双击才覆盖，避免误操作丢失当前编辑内容。

5. 编辑器外观与行为

// ====================== 编辑器外观与行为 ======================
"editor.fontSize": 14,
"editor.fontFamily": "Monaco, 'Courier New', monospace",
"editor.tabSize": 4,                   // Tab = 4 空格
"editor.insertSpaces": true,           // 用空格替代 Tab 字符
"editor.detectIndentation": false,     // 不自动检测缩进风格
"editor.renderWhitespace": "none",     // 不显示空格和 Tab 符号
"editor.lineNumbers": "on",            // 显示行号
"editor.minimap.enabled": false,       // 关闭 minimap（节省性能）
"editor.cursorStyle": "line",          // 光标样式（竖线）
"editor.smoothScrolling": true,        // 平滑滚动
"editor.lineHeight": 20,               // 行高
"editor.letterSpacing": 0.4,           // 字间距
"editor.fontLigatures": true,          // 连字（=> → ⇒，!= → ≠）

推荐字体

平台推荐字体
Windows'Cascadia Code', 'Fira Code', Consolas
macOS'SF Mono', 'Fira Code'
Linux'Fira Code', 'JetBrains Mono'
通用（兼容性最好）'Monaco', 'Courier New', monospace

6. 代码编辑优化

// ====================== 代码编辑优化 ======================
"editor.formatOnSave": true,               // 保存时自动格式化
"editor.formatOnPaste": false,             // 粘贴时不自动格式化
"editor.autoClosingBrackets": "always",    // 自动补全括号 [] {}
"editor.autoClosingQuotes": "always",      // 自动补全引号 "" ''
"editor.suggestSelection": "first",        // 按 Enter 直接选第一个建议
"editor.quickSuggestions": {               // 快速建议（输入时触发）
    "comments": true,
    "strings": true,
    "other": true
},

7. C/C++ 专项配置（clangd）

7.1 为什么用 clangd 而不是 Microsoft C/C++ IntelliSense？

对比维度Microsoft C/C++clangd
索引速度较慢（Tag Parser）极快（基于 Clang AST）
补全质量一般精确（同 Clang 编译器语义）
头文件跳转有时出错准确
跨编辑器仅 VS Code可用于 Vim / Emacs / Sublime

7.2 核心配置

// ====================== clangd 核心配置 ======================
"C_Cpp.intelliSenseEngine": "clangd",       // ★ 关键：切换到 clangd 引擎
"clangd.path": "clangd",                    // 若不在 PATH 中则写绝对路径
"C_Cpp.codeFolding": "disabled",            // 关闭旧折叠，交给 clangd

"clangd.arguments": [
    "--background-index",                   // 后台建索引，加速跳转
    "--clang-tidy",                         // 启用静态检查
    "--clang-tidy-checks=readability-redundant-delete, bugprone-suspicious-semicolon",
    "--completion-style=detailed",          // 详细补全提示
    "--header-insertion=iwyu",              // 自动添加缺失头文件

    // ★ 告诉 clangd 用什么编译器做头文件查询
    "--query-driver=C:/Program Files (x86)/GNU Arm Embedded Toolchain/10 2021.10/bin/arm-none-eabi-gcc.exe"
],

7.3 头文件路径（fallbackFlags）

当项目没有 compile_commands.json 时，clangd 需要通过 fallbackFlags 知道头文件在哪：

"clangd.fallbackFlags": [
    // ===== 全局宏定义 =====
    "-DUSE_HAL_DRIVER",
    "-DSTM32F407xx",

    // ===== 系统头文件 =====
    "-IC:/Program Files (x86)/GNU Arm Embedded Toolchain/10 2021.10/arm-none-eabi/include",

    // ===== STM32 HAL 库头文件（外置） =====
    "-ID:/Mycode/STM32_F407_GCC_TPL/Drivers/STM32F4xx_HAL_Driver/Inc",
    "-ID:/Mycode/STM32_F407_GCC_TPL/Drivers/STM32F4xx_HAL_Driver/Inc/Legacy",
    "-ID:/Mycode/STM32_F407_GCC_TPL/Drivers/CMSIS/Device/ST/STM32F4xx/Include",
    "-ID:/Mycode/STM32_F407_GCC_TPL/Drivers/CMSIS/Include",

    // ===== 项目自身头文件 =====
    "-I./Core/Inc",
    "-I./Common",
    "-I./Code",
    "-I./OnChip",
    "-I./OffChip"
],

如果你使用 CMake 生成 compile_commands.json
可在 CMakeLists.txt 中加 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)，clangd 会自动从该文件读取 -I 和 -D，此时可以删除 fallbackFlags。

7.4 保存时自动修复 + 格式化

// ===== 保存时自动 clang-tidy 修复 =====
"editor.codeActionsOnSave": {
    "source.fixAll.clang-tidy": "always"
},

// ===== 格式化工具 =====
"clang-format.executable": "D:/LLVM/mingw/bin/clang-format.exe",

// C 文件专属
"[c]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "llvm-vs-code-extensions.vscode-clangd"
},

// C++ 文件专属
"[cpp]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "llvm-vs-code-extensions.vscode-clangd"
},

// 格式化风格（LLVM 风格 + 4 空格缩进）
"C_Cpp.clang_format_style": "{ BasedOnStyle: LLVM, IndentWidth: 4 }",

下图梳理了 clangd 从索引到补全/跳转的完整工作流程：

是

否

clangd 启动

是否存在 compile_commands.json?

读取编译数据库

使用 fallbackFlags 头文件路径

后台建立索引 background-index

代码补全 / 跳转 / 诊断

保存时 clang-tidy 自动修复

clang-format 格式化

8. Python 专项配置

// ====================== Python 格式化（Black） ======================
"python.formatting.provider": "black",
"python.formatting.blackPath": "black",
"python.formatting.blackArgs": [
    "--line-length=88",                 // 每行最多 88 字符
    "--skip-string-normalization"       // 保留字符串原来的引号风格
],

// ====================== Python 文件专属设置 ======================
"[python]": {
    "editor.insertSpaces": true,        // Python 必须用空格缩进
    "editor.tabSize": 4,                // PEP 8 标准：4 空格
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "ms-python.black-formatter"
},

Python 推荐扩展

扩展 ID作用
ms-python.python核心 Python 支持
ms-python.black-formatterBlack 代码格式化
ms-python.isortimport 语句排序
ms-python.flake8代码风格检查

如需保存时自动整理 import，在 [python] 中添加：

"editor.codeActionsOnSave": {
    "source.organizeImports": true
}

9. 其他语言专项配置

JSON

"[json]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode"
},

YAML

"[yaml]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "prettier.proseWrap": "never"           // YAML 不自动折行
},

Markdown

"[markdown]": {
    "editor.quickSuggestions": {
        "other": true,
        "comments": false,
        "strings": true
    },
    "editor.wordWrap": "on",
    "editor.renderWhitespace": "none",
    "editor.tabSize": 2,
    "editor.autoClosingQuotes": "always",
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode"
},

// Markdown 预览设置
"markdown.preview.fontSize": 14,
"markdown.preview.lineHeight": 1.5,
"markdown.preview.breaks": true,           // 换行即 <br>
"markdown.preview.linkify": true,          // 自动识别链接
"markdown.preview.doubleClickToSwitchToEditor": false,

// Markdown 扩展设置（需安装 yzhang.markdown-all-in-one）
"markdown.extension.toc.levels": "2..4",
"markdown.extension.toc.unorderedList.marker": "-",
"markdown.extension.preview.autoShowPreviewToSide": true,

Makefile

"[makefile]": {
    "editor.insertSpaces": false,           // ★ Makefile 必须用 Tab！
    "editor.tabSize": 8
},

10. 文件排除与搜索排除

// ====================== 文件浏览器隐藏 ======================
"files.exclude": {
    "**/.git": true
    // "**/.vscode": true,                  // 可选：隐藏配置目录
    // "**/*.exe": true,                    // 可选：隐藏可执行文件
    // "**/*.o": true                       // 可选：隐藏编译产物
},

// ====================== 全局搜索忽略 ======================
"search.exclude": {
    "**/build": true,                       // CMake 构建目录
    "**/node_modules": true,                // Node.js 依赖
    "**/.vscode": true                      // VSCode 配置目录
},

11. 终端与调试

// ====================== 终端与调试 ======================
"terminal.integrated.defaultProfile.windows": "Command Prompt",  // 可改为 Git Bash
"terminal.integrated.fontSize": 12,
"debug.console.fontSize": 12,
"debug.showBreakpointsInOverviewRuler": true,   // 滚动条显示断点标记

Windows 用户注意：如果安装了 Git Bash 或 MSYS2，可将 defaultProfile.windows 改为 "Git Bash"。

12. Build Tasks（CMake + Ninja）

嵌入式项目推荐 CMake + Ninja 组合（比 Make 更快，且跨平台行为一致）：

"tasks": {
    "version": "2.0.0",
    "tasks": [
        {
            "label": "CMake: 配置 Ninja",
            "type": "shell",
            "command": "cmake -B build -S . -G Ninja",
            "group": "build",
            "problemMatcher": [],
            "detail": "不切换目录，生成 Ninja 构建文件"
        },
        {
            "label": "CMake: 正常编译",
            "type": "shell",
            "command": "cmake --build build",
            "group": "build",
            "problemMatcher": [],
            "detail": "常规编译，不显示完整命令行"
        },
        {
            "label": "CMake: 详细编译 显示完整命令行",
            "type": "shell",
            "command": "ninja -v -C build",
            "group": "build",
            "problemMatcher": [],
            "detail": "打印每一条编译链接命令，方便排错"
        },
        {
            "label": "CMake: 清理工程",
            "type": "shell",
            "command": "cmake --build build --target clean",
            "group": "build",
            "problemMatcher": []
        }
    ]
}

使用方式

  • Ctrl+Shift+B → 选择对应 Task
  • 或在命令面板（Ctrl+Shift+P）输入 Tasks: Run Task

推荐工作流

第一步  CMake: 配置 Ninja      →  生成 build 目录和构建文件
第二步  CMake: 正常编译         →  增量编译
排查错误    CMake: 详细编译         →  排查编译错误时使用
重新编译    CMake: 清理工程         →  全量重编前先清理

下图展示了推荐的 CMake + Ninja 构建任务流转：

是

否

是

否

Ctrl+Shift+B 选择 Task

CMake: 配置 Ninja

生成 build 目录与构建文件

CMake: 正常编译

编译是否通过?

生成固件/可执行文件

CMake: 详细编译 排查错误

需要全量重编?

CMake: 清理工程

完成

13. 附：完整可复用模板

将下面的内容保存为 my_project.code-workspace，修改其中的路径和宏定义即可用于自己的项目：

{
  "folders": [{ "path": "." }],

  "settings": {
    // ====================== 布局与外观 ======================
    "workbench.colorTheme": "Nord",
    "workbench.iconTheme": "vs-seti",
    "workbench.startupEditor": "none",
    "workbench.editor.enablePreview": false,
    "workbench.tree.renderIndentGuides": "always",

    // ====================== 编辑器通用 ======================
    "editor.fontSize": 14,
    "editor.fontFamily": "'Cascadia Code', 'Fira Code', Consolas, monospace",
    "editor.tabSize": 4,
    "editor.insertSpaces": true,
    "editor.formatOnSave": true,
    "editor.minimap.enabled": false,
    "editor.fontLigatures": true,
    "editor.detectIndentation": false,

    // ====================== C/C++ (clangd) ======================
    "C_Cpp.intelliSenseEngine": "clangd",
    "clangd.path": "clangd",
    "clangd.arguments": [
      "--background-index",
      "--clang-tidy",
      "--completion-style=detailed",
      "--header-insertion=iwyu",
    ],
    "clangd.fallbackFlags": [
      // ← 在此填写你的 -D 宏 和 -I 路径
    ],
    "[c]": {
      "editor.defaultFormatter": "llvm-vs-code-extensions.vscode-clangd",
    },
    "[cpp]": {
      "editor.defaultFormatter": "llvm-vs-code-extensions.vscode-clangd",
    },
    "editor.codeActionsOnSave": {
      "source.fixAll.clang-tidy": "always",
    },

    // ====================== Python ======================
    "[python]": {
      "editor.tabSize": 4,
      "editor.defaultFormatter": "ms-python.black-formatter",
    },

    // ====================== 其他语言 ======================
    "[json]": {
      "editor.defaultFormatter": "esbenp.prettier-vscode",
    },
    "[yaml]": {
      "editor.defaultFormatter": "esbenp.prettier-vscode",
    },
    "[markdown]": {
      "editor.wordWrap": "on",
      "editor.tabSize": 2,
      "editor.defaultFormatter": "esbenp.prettier-vscode",
    },
    "[makefile]": {
      "editor.insertSpaces": false,
      "editor.tabSize": 8,
    },

    // ====================== 排除 ======================
    "files.exclude": {
      "**/.git": true,
    },
    "search.exclude": {
      "**/build": true,
      "**/node_modules": true,
      "**/.vscode": true,
    },
  },

  "tasks": {
    "version": "2.0.0",
    "tasks": [
      {
        "label": "CMake: 配置",
        "type": "shell",
        "command": "cmake -B build -S . -G Ninja",
        "group": "build",
      },
      {
        "label": "CMake: 编译",
        "type": "shell",
        "command": "cmake --build build",
        "group": "build",
      },
      {
        "label": "CMake: 清理",
        "type": "shell",
        "command": "cmake --build build --target clean",
        "group": "build",
      },
    ],
  },
}

小结

关注点核心配置项
外观统一colorTheme、iconTheme、fontFamily
编辑器体验enablePreview: false、formatOnSave: true
C/C++ 智能提示clangd.arguments + clangd.fallbackFlags
Python 格式化ms-python.black-formatter
构建自动化tasks 中配置 CMake/Ninja 命令
工作区隔离files.exclude + search.exclude

一步到位：将 .code-workspace 文件放到项目目录，终端执行 code my_project.code-workspace 即可加载全部配置。团队成员只需修改本地的 fallbackFlags 路径即可无缝协作。

文档基于实际 STM32F407 + ARM GCC + Python 混合项目编写，更新时间：2026-09-11。

# vscode # c++ # c语言 # python
Logo
乐奇 Rokid 开放社区

更多推荐

cover

从源码拆解一个 AIUI 每日一词智能体：页面、离线索引与硬件交互

avatar 乐奇 Rokid 开放社区
cover

一句话打造「丢哪里」垃圾分类AIUI智能体

avatar 乐奇 Rokid 开放社区
cover

“什么值得买”兴趣消费服务接入乐奇AI眼镜，开启“看见即搜索”新体验

avatar 乐奇 Rokid 开放社区