VS Code 入门指南

本指南适用于 VS Code 和 Cursor. 我主力使用 Cursor，但其中的配置也完全适用于 VS Code，所以在下文中，我默认使用 VS Code 来指代这两个编辑器.

TL;DR#

如果你还没有形成自己习惯的 VS Code 配置，或者认同我的配置理念想要尝试使用，可以按照下面的步骤快速迁移到我的配置方案.

安装#

从 VS Code 官网 ↗或 Cursor 官网 ↗下载并安装.

安装过程中通常会询问是否添加 code（或 cursor）命令到系统路径，强烈建议选择安装，这样你就可以在终端中使用命令行快速打开 VS Code 了.

VS Code 入门#

VS Code 的核心理念是基于工作区的项目管理. 所谓工作区就是一个文件夹，VS Code 对其内部结构没有任何要求，这使得它能灵活地适应任何类型的项目. 虽然你也可以用 VS Code 编辑单独的文件，但那样不如用更轻量级的 CotEditor 等编辑器.

我强烈推荐为每个正式的工作任务都创建一个专门的文件夹作为项目. 项目的规模可大可小：写一个大型软件是项目，写一篇论文是项目，甚至写一个小读书报告也可以是项目. 在一个独立的项目文件夹下，你可以更好地收集和整理资源、编写文档、管理版本，最终导出交付物，整个工作流程会变得井然有序.

我的常用操作流程是：在终端中使用 mkdir <dir> 创建新文件夹，然后用 code <dir> 命令直接在 VS Code 中打开这个工作区.

当你打开一个工作区后，VS Code 的界面主要由几个部分组成：左侧是资源管理器（Explorer），用于浏览和管理项目文件；右侧是编辑区域，用于编写代码；下方是集成终端（可以用 ⌃` 快速开关），用于执行命令.

在 VS Code 中，几乎所有操作都可以通过 Command Palette 完成. 按 ⇧⌘P 打开它，然后你就可以通过输入文字来搜索并执行各种命令，比如输入 reload window 来”软重启”窗口，或者按 ⌘P 快速搜索和切换文件，还可以输入 :100 跳转到指定行. 熟练使用命令面板是提升 VS Code 操作效率的关键.

配置与插件#

VS Code 提供了两种配置界面：一种是按 ⌘, 打开的图形化界面，方便直观地进行各种设置；另一种是直接编辑 settings.json 文件，可以在图形配置界面的右上角找到打开按钮. 对于需要精确控制的高级配置，我更推荐直接编辑 JSON 文件.

UI 优化#

主题与字体#

我使用 Catppuccin ↗ 主题. 我会开启自动检测浅色和深色外观功能，配合 macOS 的自动切换外观模式，实现主题的无缝切换：浅色模式下使用 Latte 变体，深色模式下使用 Macchiato 变体. 图标使用 Catppuccin 的配套图标主题，它会根据当前选择的颜色主题自动切换到对应的图标变体，确保整体视觉风格的一致性.

安装 Catppuccin 颜色主题和图标只需要在 VS Code 中安装 Catppuccin for VSCode 和 Catppuccin Icons for VSCode 两个插件即可. 然后进行配置：

{
  // Theme
  "window.autoDetectColorScheme": true,
  "workbench.preferredDarkColorTheme": "Catppuccin Macchiato",
  "workbench.preferredLightColorTheme": "Catppuccin Latte",
  "workbench.iconTheme": "catppuccin-latte",
  "terminal.integrated.minimumContrastRatio": 1,
}

字体方面，我选择使用 Maple Mono ↗ 和 SF Mono ↗ 分别作为编辑器和终端的字体. 其中 Maple Mono 我选择 Maple Mono Normal NF CN 变体，这个变体的外观更接近 JetBrains Mono 的风格，同时支持 Nerd Font，中文字形和 ligatures. 而 SF Mono 则使用第三方制作的 SF Mono Nerd Font Ligaturized 变体，给 Apple 的 SF Mono 添加了 Nerd Font 和 ligatures 支持.

{
  // Font
  "editor.fontFamily": "'Maple Mono Normal NF CN'",
  "editor.fontSize": 13,
  "editor.lineHeight": 1.2,
  "editor.fontLigatures": true,
  "terminal.integrated.fontFamily": "'Liga SFMono Nerd Font'",
  "terminal.integrated.fontSize": 13,
}

Minimap#

VS Code 的 minimap 功能可以在编辑器右侧显示当前文件的代码缩略图，提供文件全貌的可视化概览. 它不仅能让你快速浏览整个文件的结构，还能高亮显示 Git 修改的区域（增删改的代码行），以及精确定位 linter 警告和错误的位置. 我会关闭了字符渲染功能，因为在如此小的缩略图中，具体的字符内容并不重要，关闭后 minimap 会以更简洁的色块形式显示.

{
  // Minimap
  "editor.minimap.enabled": true,
  "editor.minimap.renderCharacters": false,
}

Smooth Animation#

我启用了 VS Code 的所有平滑动画效果. 这些动画包括编辑器的平滑滚动、工作区列表的平滑滚动、终端的平滑滚动，以及光标的平滑闪烁和移动动画. 虽然这些动画效果会略微增加 GPU 使用率，但它们能显著改善视觉体验，让界面操作感觉更加流畅和现代化，特别是在高刷新率显示器上效果更为明显.

{
  // Smooth Animation
  "editor.smoothScrolling": true,
  "workbench.list.smoothScrolling": true,
  "terminal.integrated.smoothScrolling": true,
  "editor.cursorBlinking": "smooth",
  "editor.cursorSmoothCaretAnimation": "on",
}

其他优化#

• 增加工作区树形结构的缩进间距，让文件层级关系更加清晰易读.
• 在编辑器中显示 100 字符的垂直参考线，帮助保持代码的可读性.
• 启用自动换行并使用高级换行策略，确保长行代码在窄屏幕上也能良好显示，高级策略在处理中英混排时能提供更好的换行效果.
• 使用 VS Code 内置的文件对话框替代系统原生对话框.
• 禁用 terminal 右侧的 tab panel，最大化利用终端的横向显示空间.
• 启用括号对引导线，显示当前活跃括号对之间的连接线，帮助快速识别当前代码块中的内容.

{
  // UI Misc
  "workbench.tree.indent": 12,
  "editor.rulers": [100],
  "editor.wordWrap": "on",
  "editor.wrappingStrategy": "advanced",
  "files.simpleDialog.enable": true,
  "terminal.integrated.tabs.enabled": false,
  "editor.guides.bracketPairs": "active",
}

UX 优化#

自动保存#

强烈推荐开启自动保存功能. 这不仅是现代编辑器的标配，更能有效防止因忘记保存、程序崩溃或意外关机导致的工作丢失. 同时，它还能将你从”运行前先手动保存”的肌肉记忆中解放出来，减轻了不必要的心智负担，让你能够更专注于编码本身.

{
  "files.autoSave": "afterDelay",
}

自动格式化#

由于我们已经启用了自动保存，保存快捷键 ⌘S 实际上已经失去了原有的作用. 这个功能等于是将闲置的 ⌘S 重新绑定到格式化操作上（⌥⇧F），让操作更加简便. 配合后续提到的 “fix all on save” 和 “sort import on save” 等功能，我们可以通过一次保存操作同时完成代码格式化、错误修复和导入排序，大大提升代码维护的效率.

{
  "editor.formatOnSave": true,
}

文件排序#

将 VS Code 的文件排序方式改为按类型排序，方便快速找到同类型的文件. 个人觉得比默认的按字母排序更实用.

{
  "explorer.sortOrder": "type",
}

其他优化#

• 禁用文件删除确认和拖拽确认的确认对话框.
• 禁用自动端口转发功能，避免误触发，我会在需要时手动转发.
• 禁用传统的代码自动建议功能，在 AI 编程时代，Cursor Tab 以及 Copilot 等都要远好于 quick suggestions.

{
  "explorer.confirmDelete": false,
  "explorer.confirmDragAndDrop": false,
  "remote.autoForwardPorts": false,
  "editor.quickSuggestions": {
    "other": false,
    "comments": false,
    "strings": false
  },
}

特定配置#

除了通用的编辑器配置外，针对不同的编程语言和开发工具，我也进行了一些针对性的优化配置. 如果你也使用这些工具，可以参考我的配置思路；如果暂时用不到，可以直接跳过相应部分.

Git#

VS Code 内置了基础的 Git 支持，你可以在左侧侧边栏中进行可视化的 Git 操作. 我还安装了 Git History, Git Graph 和 GitLens 三个增强插件，它们提供了图形化历史查看、文件历史追踪等丰富功能. 具体配置如下：

• 启用自动 fetch 功能，让本地仓库始终与远程保持同步.
• 禁用同步确认对话框.
• 关闭 Git Graph 和 GitLens 的大部分常驻显示，避免界面过于复杂，需要时再手动打开相应功能.
• 在差异对比时忽略空白字符差异，并启用未更改区域折叠，专注于实质性的代码变更.

{
  // Git
  "git.autofetch": true,
  "git.confirmSync": false,

  // Git Graph
  "git-graph.showStatusBarItem": false,

  // GitLens
  "gitlens.currentLine.enabled": false,
  "gitlens.codeLens.enabled": false,
  "gitlens.graph.statusBar.enabled": false,
  "gitlens.launchpad.indicator.enabled": false,

  // Diff
  "diffEditor.ignoreTrimWhitespace": true,
  "diffEditor.hideUnchangedRegions.enabled": true,
}

Python#

安装 Python 插件以支持基本的 Python 开发. 我额外安装了 Ruff 插件作为默认格式化工具，它比传统的 Black + isort 组合更快且功能更全面，能够在保存时自动执行导入排序和代码修复（如自动移除未使用的导入），让代码始终保持规范和整洁. 同时，我禁用了 Just My Code 调试模式，这样调试器可以进入第三方库代码，方便深入排查问题和理解库的实现细节.

{
  // Python
  "debugpy.debugJustMyCode": false,
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit",
      "source.fixAll": "explicit"
    }
  },
}

Jupyter#

Jupyter Notebook 是 Python 开发中的重要交互式工具，特别适合数据探索和学习实验. 安装 Jupyter 插件包即可在 VS Code 中获得完整的 notebook 体验，我还额外安装了 Jupyter PowerToys 插件来增强功能.

配置方面大多延续了前面提到的理念：禁用 Just My Code 调试模式以便深入调试，关闭内核重启确认减少打扰，启用输出自动换行保持内容可读性，开启保存时格式化维持代码整洁，以及让 matplotlib 图表主题与编辑器保持一致，同时在保存时自动执行导入排序和问题修复.

{
  // Jupyter
  "jupyter.debugJustMyCode": false,
  "jupyter.askForKernelRestart": false,
  "notebook.output.wordWrap": true,
  "notebook.formatOnSave.enabled": true,
  "jupyter.themeMatplotlibPlots": true,
  "notebook.codeActionsOnSave": {
    "notebook.source.organizeImports": "explicit",
    "notebook.source.fixAll": "explicit"
  },
}

Prettier#

前端开发相关的语言统一使用 Prettier 进行格式化. 我将这些语言的默认格式化工具设置为 Prettier，并采用 2 个空格的缩进（Prettier 默认配置），保持前端代码风格的一致性.

{
  // Prettier
  "[javascript][typescript][json][jsonc][css][html][yaml][markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  },
}

LaTeX#

我使用 LaTeX Workshop 插件进行 LaTeX 文档编辑. 由于我主要编写英文文档，无需对构建配方进行额外配置. 我的配置重点在于减少干扰和提升格式化体验：

• 禁用 warning 的弹窗
• 忽略 underfull badbox 信息
• 使用 tex-fmt 进行代码格式化

注意：你需要单独安装 tex-fmt 程序，安装方式参见开头的 TL;DR 部分.

{
  // LaTeX
  "latex-workshop.message.warning.show": false,
  "latex-workshop.message.badbox.show": "overfull",
  "latex-workshop.formatting.latex": "tex-fmt",
}

Typst#

Typst 是基于 Rust 的现代排版系统，它完全摆脱了 LaTeX 的历史包袱，提供现代化的语法设计、近乎实时的编译速度和友好的错误提示体验.

安装 Tinymist Typst 插件即可开始 Typst 编辑. 我的主要配置是启用输入时实时编译和使用 typstyle 作为格式化工具，让排版过程更加即时和流畅：

{
  // Typst
  "tinymist.exportPdf": "onType",
  "tinymist.formatterMode": "typstyle",
}

Markdown#

Markdown 及其衍生格式 MDX 是我日常写作的主要工具. 由于 Markdown 对缩进和空白字符十分敏感，加上我在写作时经常需要混合不同缩进层级的代码示例，因此我针对 Markdown 文件做了专门的显示优化：

• 禁用缩进引导线，避免在不同的缩进大小中产生视觉干扰.
• 启用边界空白字符渲染，让行首和行尾的空格可见.
• 关闭 indent-rainbow 插件的彩虹缩进效果.

{
  // Markdown
  "[markdown][mdx]": {
    "editor.renderWhitespace": "boundary",
    "editor.guides.indentation": false
  },
  "indentRainbow.excludedLanguages": ["markdown", "mdx"],
}

Remote - SSH#

我使用 Remote - SSH 插件进行远程开发，它让我可以在本地 VS Code 中直接编辑和运行远程服务器上的代码.

为了确保稳定的连接体验，特别是在网络环境复杂的情况下，我配置了优先从本地下载服务端程序和扩展，然后上传到服务器. 这样可以充分利用本地的科学上网服务，避免远程服务器直接下载时可能遇到的网络问题：

{
  // Remote - SSH
  "remote.SSH.localServerDownload": "always",
  "remote.downloadExtensionsLocally": true,
}

Error Lens#

Error Lens 是一个优秀的错误提示增强插件，能够在代码行内直接显示错误和警告信息，让问题定位更加直观.

我主要调整了其显示效果配置，在保持功能性的同时避免过于繁杂的视觉干扰. 关于每个配置选项的具体效果，可以参考官方文档 ↗了解详情.

{
  // Error Lens
  "errorLens.followCursor": "closestProblem",
  "errorLens.delay": 2000,
  "errorLens.enabledInMergeConflict": false,
  "errorLens.fontStyleItalic": true,
  "errorLens.messageBackgroundMode": "message",
  "errorLens.messageTemplate": "$message - $source",
  "errorLens.padding": "0 0.5ch",
  "errorLens.messageMaxChars": 100,
  "errorLens.gutterIconsEnabled": true,
  "errorLens.gutterIconSet": "defaultOutline",
  "errorLens.gutterIconSize": "125%",
}

Cursor#

针对 Cursor 编辑器的专门配置，我启用了字符级别的差异对比功能.

{
  // Cursor
  "cursor.diffs.useCharacterLevelDiffs": true,
}

其他插件#

• x86 and x86_64 Assembly：用于 x86 和 x86_64 汇编语言的语法高亮.
• CodeSnap：用于漂亮地截取代码片段并生成图片.
• Astro：用于支持 Astro 语言.
• Debug Visualizer：用于可视化调试.
• Rainbow CSV：用于高亮 CSV 文件.
• Hex Editor：用于编辑二进制文件.
• vscode-just：用于高亮 justfile 文件.
• indent-rainbow：将不同的缩进层级用不同颜色高亮.
• Even Better TOML：用于支持 TOML 文件.
• ShellCheck：给你的 shell 脚本提出修改建议.
• MDX：用于支持 MDX 文件.
• WakaTime：用于记录代码时间. 可自建 server. 参考 TL;DR 部分.
• TODO Hightlight：用于高亮 TODO 注释.

快捷键#

这里列出的是最常用的快捷键，强烈建议你花时间记住它们，这能显著提升你的操作效率. 对于那些不太常用的操作，直接通过 Command Palette 来完成就足够了. 另外，你也可以在 Command Palette 中搜索特定功能来查看其对应的快捷键，这样能帮助你逐步掌握符合自己工作流的快捷键组合.

Command Palette#

• ⇧⌘P：打开 Command Palette
• ⌘P：在当前工作区中搜索文件
• ⇧⌘O：在当前文件中搜索符号
• ⌘T：在当前工作区中搜索文件
• ⌃G：跳转到指定行

Editor Group (Tabs)#

• ⌘W：关闭当前 Tab
• ⌘K W：关闭当前 group 中的所有 Tab
• ⌘K ⌘W：关闭所有 Tab
• ⌘1 / ⌘2 / ⌘3 / ⌘4：切换到指定 group
• ⌃Tab：在当前 group 中切换到最近使用的 Tab

Layout#

• ⌘B：切换显示左边的 sidebar
• ⌘J：切换显示下侧的 panel

Navigation History#

• ⌃-：后退
• ⌃⇧-：前进

Editing#

• ⌘D：选择下一个匹配项
• 按住 ⌥⇧ 并拖动：矩形选择
• ⌥↑ / ⌥↓：向上/向下移动行
• ⌥⇧↑ / ⌥⇧↓：向上/向下复制行

Misc#

• ⌃R：切换最近使用的工作区