VS Code 安装与配置指南

前言

本文档用于记录新 MacBook 上 Visual Studio Code 的完整安装和配置流程，包括下载安装、命令行启动、基础设置、常用插件、C/C++ 开发环境配置，以及后续维护方式。

本文默认已经完成主指南中的 Homebrew 安装。如果尚未安装 Homebrew，请先回到 MacBook 设置指南的“开发环境配置”部分完成 Homebrew 配置。

1. 安装 VS Code

1.1 官方下载方式

官方网站：Visual Studio Code
macOS 安装说明：Installing Visual Studio Code on macOS
下载页：VS Code Download

安装步骤：

打开 VS Code 下载页。
根据 Mac 芯片选择版本：
- Apple Silicon Mac：选择 Apple silicon 或 Universal 版本。
- Intel Mac：选择 Intel chip 或 Universal 版本。
下载 .dmg 安装包。
打开 .dmg 文件。
将 Visual Studio Code.app 拖入“应用程序”文件夹。
从“应用程序”中打开 VS Code。

1.2 通过 Homebrew 安装

如果希望让 Homebrew 管理 VS Code，可以使用 Homebrew Cask：

brew install --cask visual-studio-code

说明：

Homebrew cask 名称是 visual-studio-code。
安装后 App 名称是 Visual Studio Code.app。
后续可通过 brew upgrade --cask visual-studio-code 更新。

1.3 固定到程序坞

打开 VS Code 后：

在程序坞中右键点击 VS Code 图标。
选择 选项 -> 在程序坞中保留。

2. 配置 code 命令

配置后可以在终端中使用 code . 打开当前文件夹。

2.1 通过 VS Code 命令面板配置

打开 VS Code。
按 Command + Shift + P 打开命令面板。
搜索 shell command。
运行：

Shell Command: Install 'code' command in PATH

关闭并重新打开终端。
验证：

command -v code
code --version
code .

2.2 手动配置 PATH

如果命令面板方式失败，可以手动加入 zsh 配置：

cat <<'EOF' >> ~/.zprofile
# Add Visual Studio Code CLI
export PATH="$PATH:/Applications/Visual Studio Code.app/Contents/Resources/app/bin"
EOF
source ~/.zprofile

再次验证：

command -v code
code --version

3. 基础设置

3.1 打开 Settings JSON

打开 VS Code。
按 Command + Shift + P。
搜索并运行：

Preferences: Open User Settings (JSON)

3.2 推荐用户设置

可以将以下内容合并到用户级 settings.json 中：

{
  "workbench.startupEditor": "none",
  "workbench.sideBar.location": "left",
  "workbench.editor.enablePreview": false,

  "editor.fontSize": 14,
  "editor.lineHeight": 22,
  "editor.tabSize": 4,
  "editor.insertSpaces": true,
  "editor.wordWrap": "on",
  "editor.minimap.enabled": false,
  "editor.renderWhitespace": "boundary",
  "editor.rulers": [80, 120],
  "editor.formatOnSave": true,
  "editor.suggestSelection": "first",

  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000,
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "files.trimFinalNewlines": true,

  "terminal.integrated.defaultProfile.osx": "zsh",
  "terminal.integrated.scrollback": 10000,

  "explorer.confirmDelete": true,
  "explorer.confirmDragAndDrop": true,

  "git.autofetch": true,
  "git.confirmSync": false
}

说明：

editor.formatOnSave 会在保存时自动格式化，需要对应语言安装格式化插件。
files.trimTrailingWhitespace 会删除行尾空格，适合代码文件。
workbench.editor.enablePreview 关闭预览标签页，打开文件时更稳定。

4. 常用插件安装

4.1 插件安装方式

图形界面安装：

打开 VS Code。
点击左侧扩展图标。
搜索插件名称。
点击 Install。

命令行安装：

code --install-extension <extension-id>

查看已安装插件：

code --list-extensions

导出插件清单：

code --list-extensions > vscode-extensions.txt

在新机器恢复插件：

while read extension; do
  code --install-extension "$extension"
done < vscode-extensions.txt

4.2 推荐插件清单

分类	插件	Extension ID	用途
中文界面	Chinese (Simplified) Language Pack	`MS-CEINTL.vscode-language-pack-zh-hans`	VS Code 简体中文界面
C/C++	C/C++	`ms-vscode.cpptools`	C/C++ IntelliSense、调试和代码浏览
C/C++	CMake Tools	`ms-vscode.cmake-tools`	CMake 项目配置、构建和调试
C/C++	CodeLLDB	`vadimcn.vscode-lldb`	可选 LLDB 调试器插件
C/C++	clangd	`llvm-vs-code-extensions.vscode-clangd`	可选 clangd 语言服务
Python	Python	`ms-python.python`	Python 开发基础插件
Python	Pylance	`ms-python.vscode-pylance`	Python 类型检查和智能提示
Python	Jupyter	`ms-toolsai.jupyter`	Notebook 支持
JavaScript	ESLint	`dbaeumer.vscode-eslint`	JavaScript/TypeScript 代码检查
JavaScript	Prettier	`esbenp.prettier-vscode`	前端代码格式化
Git	GitLens	`eamodio.gitlens`	Git 历史、Blame 和提交追踪
Git	Git Graph	`mhutchie.git-graph`	Git 分支和提交图
Markdown	Markdown All in One	`yzhang.markdown-all-in-one`	Markdown 编辑增强
Markdown	markdownlint	`DavidAnson.vscode-markdownlint`	Markdown 格式检查
远程开发	Remote - SSH	`ms-vscode-remote.remote-ssh`	通过 SSH 连接远程服务器
容器	Dev Containers	`ms-vscode-remote.remote-containers`	在容器中开发
容器	Docker	`ms-azuretools.vscode-docker`	Docker 文件、镜像和容器管理
通用增强	Error Lens	`usernamehw.errorlens`	将错误和警告直接显示在代码行内
通用增强	Code Spell Checker	`streetsidesoftware.code-spell-checker`	英文拼写检查

4.3 一次性安装常用插件

code --install-extension MS-CEINTL.vscode-language-pack-zh-hans
code --install-extension ms-vscode.cpptools
code --install-extension ms-vscode.cmake-tools
code --install-extension vadimcn.vscode-lldb
code --install-extension ms-python.python
code --install-extension ms-python.vscode-pylance
code --install-extension ms-toolsai.jupyter
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension eamodio.gitlens
code --install-extension mhutchie.git-graph
code --install-extension yzhang.markdown-all-in-one
code --install-extension DavidAnson.vscode-markdownlint
code --install-extension ms-vscode-remote.remote-ssh
code --install-extension ms-vscode-remote.remote-containers
code --install-extension ms-azuretools.vscode-docker
code --install-extension usernamehw.errorlens
code --install-extension streetsidesoftware.code-spell-checker

4.4 C/C++ 插件选择建议

默认推荐：

ms-vscode.cpptools
ms-vscode.cmake-tools
vadimcn.vscode-lldb

可选：

llvm-vs-code-extensions.vscode-clangd

注意：

cpptools 和 clangd 都会提供 C/C++ 智能提示。
普通项目先使用 cpptools。
如果项目使用 CMake 并生成 compile_commands.json，且希望使用 clangd 的补全和诊断，可以再启用 clangd。
不建议在不理解配置的情况下同时让 cpptools 和 clangd 对同一项目提供重复诊断。

5. C/C++ 环境配置

5.1 安装命令行开发工具

macOS 上先安装 Apple Command Line Tools：

xcode-select --install

验证：

clang --version
clang++ --version
lldb --version

5.2 通过 Homebrew 安装 C/C++ 工具链

brew install llvm cmake ninja pkgconf ccache

验证：

clang --version
clang++ --version
cmake --version
ninja --version
pkg-config --version
ccache --version

5.3 配置 Homebrew LLVM 到 PATH

Homebrew 安装的 LLVM 不会默认覆盖系统自带的 Apple Clang。如果希望优先使用 Homebrew LLVM，可以加入 PATH。

Apple Silicon Mac：

echo 'export PATH="/opt/homebrew/opt/llvm/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

Intel Mac：

echo 'export PATH="/usr/local/opt/llvm/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

验证当前使用的编译器：

which clang
which clang++
clang --version

说明：

如果输出路径是 /usr/bin/clang，使用的是 Apple Clang。
如果输出路径包含 /opt/homebrew/opt/llvm/bin 或 /usr/local/opt/llvm/bin，使用的是 Homebrew LLVM。

6. VS Code 配置 C/C++ 项目

6.1 创建测试项目

mkdir -p ~/Projects/cpp/hello-vscode
cd ~/Projects/cpp/hello-vscode
code .

创建 main.cpp：

#include <iostream>
#include <string>
#include <vector>

int main() {
    std::vector<std::string> words = {"Hello", "C++", "from", "VS Code"};

    for (const auto& word : words) {
        std::cout << word << " ";
    }

    std::cout << std::endl;
    return 0;
}

6.2 使用 CMake 管理项目

创建 CMakeLists.txt：

cmake_minimum_required(VERSION 3.20)

project(hello_vscode LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

add_executable(hello_vscode main.cpp)

6.3 配置 VS Code 工作区设置

创建 .vscode/settings.json：

{
  "cmake.generator": "Ninja",
  "cmake.buildDirectory": "${workspaceFolder}/build",
  "C_Cpp.default.cppStandard": "c++20",
  "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
  "C_Cpp.default.compileCommands": "${workspaceFolder}/build/compile_commands.json"
}

如果使用 Homebrew LLVM，并且希望显式指定编译器，可以加入以下配置。

Apple Silicon Mac：

{
  "C_Cpp.default.compilerPath": "/opt/homebrew/opt/llvm/bin/clang++"
}

Intel Mac：

{
  "C_Cpp.default.compilerPath": "/usr/local/opt/llvm/bin/clang++"
}

注意：上面两个 JSON 片段不能直接作为完整配置覆盖原有文件，应合并到同一个 .vscode/settings.json 中。

6.4 使用 CMake Tools 构建

在 VS Code 中：

按 Command + Shift + P。
运行 CMake: Configure。
选择合适的 Kit，例如 Apple Clang 或 Homebrew Clang。
运行 CMake: Build。
运行 CMake: Run Without Debugging 或 CMake: Debug。

也可以在终端中验证：

cmake -S . -B build -G Ninja
cmake --build build
./build/hello_vscode

预期输出：

Hello C++ from VS Code

6.5 单文件 C++ 编译方式

对于临时单文件测试，也可以直接在终端编译：

clang++ -std=c++20 -Wall -Wextra -O0 -g main.cpp -o main
./main

如果希望用 VS Code 任务编译单文件，可以创建 .vscode/tasks.json：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build active C++ file",
      "type": "shell",
      "command": "clang++",
      "args": [
        "-std=c++20",
        "-Wall",
        "-Wextra",
        "-O0",
        "-g",
        "${file}",
        "-o",
        "${fileDirname}/${fileBasenameNoExtension}"
      ],
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "problemMatcher": ["$gcc"]
    }
  ]
}

运行方式：

Terminal -> Run Build Task

或使用快捷键：

Command + Shift + B

7. 调试配置

7.1 推荐方式：使用 CMake Tools 调试

对于 CMake 项目，优先使用 CMake Tools：

CMake: Configure
CMake: Build
在 main.cpp 中设置断点。
运行 CMake: Debug。

这种方式会自动使用当前 CMake target，配置成本低。

7.2 可选方式：使用 CodeLLDB

如果安装了 CodeLLDB，可以为单文件或简单项目创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "lldb",
      "request": "launch",
      "name": "Debug current C++ file",
      "program": "${fileDirname}/${fileBasenameNoExtension}",
      "args": [],
      "cwd": "${fileDirname}",
      "preLaunchTask": "Build active C++ file"
    }
  ]
}

使用前需要先创建上一节的 tasks.json。

8. Git 与终端集成

8.1 将 VS Code 设置为 Git 编辑器

git config --global core.editor "code --wait"

验证：

git config --global core.editor

8.2 在 VS Code 中使用集成终端

打开终端：

Terminal -> New Terminal

常用快捷键：

Control + `

确保默认 Shell 是 zsh：

echo $SHELL

9. 默认打开方式

9.1 将文本和代码文件默认使用 VS Code 打开

对 .txt、.md、.py、.cpp、.h、.json、.yaml 等文件分别设置：

在 Finder 中右键点击该类型文件。
选择“显示简介”。
找到“打开方式”。
选择 Visual Studio Code。
点击“全部更改”。

9.2 常见建议

Markdown 文件：默认使用 VS Code 打开。
代码文件：默认使用 VS Code 打开。
Office 文档：不要设置为 VS Code，仍使用 WPS 或 Office。
图片、PDF、视频：保持系统默认或专业软件默认。

10. 更新与维护

10.1 更新 VS Code

如果从官网 .dmg 安装，VS Code 通常会自动提示更新。

如果通过 Homebrew 安装：

brew update
brew upgrade --cask visual-studio-code

10.2 更新插件

VS Code 会自动检查插件更新。也可以在扩展面板中手动更新。

查看插件列表：

code --list-extensions

10.3 备份 VS Code 配置

需要备份的内容：

~/Library/Application Support/Code/User/settings.json
~/Library/Application Support/Code/User/keybindings.json
~/Library/Application Support/Code/User/snippets/

导出插件列表：

code --list-extensions > vscode-extensions.txt

10.4 开启 Settings Sync

如果使用 Microsoft 或 GitHub 账号，可以在 VS Code 中开启 Settings Sync：

点击左下角账号图标。
选择 Turn on Settings Sync。
选择同步内容，例如 Settings、Keyboard Shortcuts、Extensions、Snippets。
登录账号并确认同步。

11. 常见问题

11.1 终端中找不到 code 命令

重新在 VS Code 中执行：

Shell Command: Install 'code' command in PATH

然后重启终端。

如果仍然失败，检查：

echo $PATH
ls "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code"

11.2 C++ 插件没有智能提示

检查：

clang++ --version
cmake --version
code --list-extensions | grep -E 'cpptools|cmake-tools|clangd'

如果是 CMake 项目，先运行：

CMake: Configure

再重新打开源文件。

11.3 CMake 找不到编译器

检查：

which clang
which clang++
cmake --version
ninja --version

如果使用 Homebrew LLVM，确认 PATH 配置已经生效：

echo $PATH

然后删除旧构建目录并重新配置：

rm -rf build
cmake -S . -B build -G Ninja

11.4 插件太多导致 VS Code 卡顿

建议：

禁用暂时不用的语言插件。
不要同时启用多个 C/C++ 语言服务。
对大目录添加排除规则，例如数据集、模型文件、构建产物。

可以在 settings.json 中加入：

{
  "files.exclude": {
    "**/build": true,
    "**/.venv": true,
    "**/__pycache__": true
  },
  "search.exclude": {
    "**/build": true,
    "**/.venv": true,
    "**/node_modules": true,
    "**/.git": true
  }
}

12. 最终验证清单

code --version
code --list-extensions
clang++ --version
cmake --version
ninja --version
git config --global core.editor

手动验证：

code . 可以从终端打开当前目录。
VS Code 可以打开集成终端。
C/C++ 插件可以识别 main.cpp。
CMake Tools 可以 Configure、Build、Run。
Markdown 文件和代码文件默认用 VS Code 打开。