第 2 章 · VS Code 通用扩展

一句话：不分语言、哪个项目都用得上的扩展：Git 增强、远程开发、格式化、Markdown、配置文件和界面。 用它还是用别的：先装 Remote、EditorConfig、Prettier 这类团队共用的，写进 .vscode/extensions.json；主题、图标这类个人偏好只装在自己机器上，不写进仓库。核对版本：VS Code 1.138，2026-10

2.1 安装与版本

图形界面：按 Ctrl+Shift+X 打开扩展视图，搜索框里输入扩展名或扩展 ID，点“安装”。搜索框输入 @installed 只看已装的，输入 @recommended 看当前项目推荐的。

命令行在三个平台上写法相同，适合写进新机器的初始化脚本：

code --install-extension esbenp.prettier-vscode

看装了哪些扩展和各自的版本，向别人报问题时把这份列表一起贴上：

code --list-extensions --show-versions

卸载：

code --uninstall-extension esbenp.prettier-vscode

公司网络连不上扩展市场时，在能上网的机器上从扩展的市场页面下载 .vsix 文件，拷过来离线安装。图形界面里是扩展视图右上角 ... 菜单的“从 VSIX 安装…”：

code --install-extension <文件>.vsix

--install-extension 后面加 --force 会把已装的扩展更新到最新版；ID 后面接 @版本号（如 [email protected]）装指定版本，新版有问题时用它退回。

2.2 五分钟概念

扩展与扩展 ID（Extension ID）：每个扩展有一个“发布者.名字”格式的 ID，如 esbenp.prettier-vscode。市场里同名的扩展可能有好几个，命令行、推荐列表和设置里都只认 ID，不认显示名。ID 在扩展详情页右侧的“Marketplace 信息”里，也可以在扩展上右键“复制扩展 ID”。
扩展市场（Marketplace）：微软的扩展仓库，VS Code 默认从这里搜索、安装和自动更新。详情页上的安装量、最近更新日期和发布者的蓝色认证标记，是判断一个扩展靠不靠谱的三个依据。
推荐扩展（Recommendations）：项目里 .vscode/extensions.json 的 recommendations 列出这个项目需要的扩展 ID。提交进仓库后，同事打开项目时右下角会提示一键安装，不用口头传话。
工作区信任（Workspace Trust）：打开陌生文件夹时 VS Code 会问是否信任作者。选“否”进入受限模式（Restricted Mode），不支持受限模式的扩展被禁用，扩展视图里标“在受限模式下禁用”。扩展能读写文件、运行命令，恶意仓库可以借扩展执行代码，所以要先问。
配置文件（Profile）：一套独立的扩展、设置、快捷键组合。写 Python 用一个，写前端用另一个，互不干扰；每个文件夹记住上次用的配置文件。扩展装在哪个配置文件里，只在那个配置文件里生效。
按工作区禁用：扩展上右键选“禁用(工作区)”，只在当前项目里关掉它，其他项目照常使用。比卸载再重装省事，排查扩展冲突时也这样逐个关。

2.3 常用扩展

括号里的 ID 可直接用于 code --install-extension。表里的扩展都在 VS Code 1.138 上实际装过；同一用途有好几个扩展时，只列装机量大、仍在维护的那个。

扩展	装它干什么	注意
Git
GitLens（`eamodio.gitlens`）	每行末尾显示最后修改人和提交说明，悬停看完整提交	标着 Pro 的功能要登录 GitKraken 账号，部分要付费
Git Graph（`mhutchie.git-graph`）	图形化看分支和提交历史，右键切换、合并、拣选提交	命令面板运行“Git Graph: View Git Graph”打开
远程
Remote - SSH（`ms-vscode-remote.remote-ssh`）	连上服务器，直接打开和编辑服务器上的文件夹	第一次连接要在服务器上下载 VS Code Server，服务器要能上外网
WSL（`ms-vscode-remote.remote-wsl`）	在 Windows 上打开 WSL 里的项目，终端和调试都在 Linux 里跑	只在 Windows 上有用；在 WSL 终端里运行 `code .` 最快
Dev Containers（`ms-vscode-remote.remote-containers`）	按项目里的 `.devcontainer/devcontainer.json` 起容器，在容器里开发	本机要先装好 Docker（见第 12 章）
格式与规范
EditorConfig（`EditorConfig.EditorConfig`）	读项目里的 `.editorconfig`，统一缩进、换行和文件末尾空行	不会主动改已有文件，保存时才按规则处理
Prettier（`esbenp.prettier-vscode`）	格式化 JS、TS、CSS、JSON、Markdown、YAML	要设为该语言的 `editor.defaultFormatter`，否则保存时不生效
Code Spell Checker（`streetsidesoftware.code-spell-checker`）	标出代码和注释里拼错的英文单词	拼音和专有名词会被误标，加进 `cSpell.words`
Error Lens（`usernamehw.errorlens`）	把报错和警告直接显示在出错那一行的末尾	嫌吵时设 `errorLens.enabledDiagnosticLevels` 只显示 error
文档
Markdown All in One（`yzhang.markdown-all-in-one`）	生成目录、列表回车自动续号、加粗斜体快捷键	在 Markdown 文件里 `Ctrl+B`（macOS `Cmd+B`）变成加粗，不再收起侧边栏
markdownlint（`DavidAnson.vscode-markdownlint`）	检查 Markdown 写法，标题层级、列表缩进不规范时画波浪线	规则在项目根目录的 `.markdownlint.json` 里开关
Markdown Preview Mermaid Support（`bierner.markdown-mermaid`）	内置 Markdown 预览里把 mermaid 代码块画成图	只影响 VS Code 预览，GitHub 网页有自己的渲染
数据与配置
YAML（`redhat.vscode-yaml`）	YAML 校验和补全，自动识别 Compose、GitHub Actions 等文件的格式	Red Hat 遥测由 `redhat.telemetry.enabled` 控制
Even Better TOML（`tamasfe.even-better-toml`）	`pyproject.toml`、`Cargo.toml` 的高亮、校验和格式化	自带格式化器，和别的 TOML 扩展同时装会抢格式化
Rainbow CSV（`mechatroner.rainbow-csv`）	CSV、TSV 每列一种颜色，悬停显示列名	还能用类 SQL 的 RBQL 查询 CSV
容器与接口
Container Tools（`ms-azuretools.vscode-containers`）	管理镜像、容器和 Compose，Dockerfile 补全，右键看容器日志	旧的 Docker 扩展（`ms-azuretools.vscode-docker`）现在只是装上它的扩展包；本机要有 Docker 或 Podman
REST Client（`humao.rest-client`）	在 `.http` 文件里写 HTTP 请求，点“Send Request”看响应	`.http` 文件可提交进仓库，团队共用同一套接口调用示例
界面与效率
中文语言包（`MS-CEINTL.vscode-language-pack-zh-hans`）	菜单、设置、提示变成简体中文	装完运行“Configure Display Language”选 `zh-cn` 并重启；命令面板仍可输英文命令名
Material Icon Theme（`PKief.material-icon-theme`）	文件树按文件类型显示图标，一眼分清配置和源码	没变化就运行“Preferences: File Icon Theme”选它
Todo Tree（`Gruntfuggly.todo-tree`）	把全项目的 `TODO`、`FIXME` 注释收进侧边栏的一棵树	大仓库扫描慢，在 `todo-tree.filtering.excludeGlobs` 里排除依赖目录
Path Intellisense（`christian-kohler.path-intellisense`）	输入相对路径时补全文件名	JS、TS 自带路径补全，它主要对 HTML、CSS、Markdown 有用
AI 编程助手
GitHub Copilot（内置，`GitHub.copilot-chat`）	代码补全和对话式编程，登录 GitHub 账号即可用	VS Code 1.138 已内置，不用另装；AI 编程助手另见本站 AI 分类

2.4 典型工作流

给团队定一套推荐扩展

新同事拉下仓库就能装齐扩展，不用一个个问：

命令面板运行“Extensions: Configure Recommended Extensions (Workspace Folder)”，生成 .vscode/extensions.json。
在 recommendations 里写上扩展 ID，如 "esbenp.prettier-vscode"（写法见 2.5）；也可以在扩展视图里右键扩展，选“添加到工作区建议”。
暂存这个文件：git add .vscode/extensions.json。
提交并推送：git commit -m "添加推荐扩展"，再 git push。
同事拉取后打开项目：code .。
右下角弹出提示，问是否安装这个存储库推荐的扩展（会列出扩展名），点“安装”；错过了就在扩展视图搜索框输入 @recommended。
核对装齐了没有：code --list-extensions。

用 Remote - SSH 在服务器上改代码

代码和运行环境都在服务器上，本地只负责显示：

装扩展：code --install-extension ms-vscode-remote.remote-ssh。
先在终端确认能登录，最好已配好密钥免密登录（详见第 6 章）：ssh <用户>@<主机>。
按 Ctrl+Shift+P，运行“Remote-SSH: Connect to Host…”，从列表里选主机，列表来自 ~/.ssh/config。
新窗口问远程平台时选 Linux；第一次会在服务器上装 VS Code Server，完成后左下角显示 SSH: <主机>。
运行“File: Open Folder…”，输入服务器上的路径：/home/<用户>/<项目>。
打开扩展视图，在项目要用的语言扩展上点“在 SSH: <主机> 中安装”，例如 ms-python.python。
用完断开：运行“Remote: Close Remote Connection”。

连上之后 VS Code 拆成两半：本地只剩界面，编辑器里的文件、终端里跑的命令、调试的进程都在服务器上。扩展也分两边装：主题、图标、语言包这类只管界面的扩展留在本地；语言支持、格式化、调试、Git 增强这类要读文件、起进程的扩展必须装在远程，所以第 6 步要在远程再装一次。WSL 和 Dev Containers 是同样的结构，只是把 SSH 换成了 WSL 和容器。

Remote - SSH 的本地与远程分工：界面类扩展在本地，语言和调试类扩展在远程

为不同项目建配置文件

写 Python 的扩展在前端项目里只会拖慢启动，反过来也一样：

按 Ctrl+Shift+P，运行“Profiles: New Profile…”，名字填“前端”，选空白或从“Default”复制。
新窗口左下角齿轮图标上显示配置文件名，扩展视图里只有复制过来的扩展。
在这个配置文件里装要用的扩展，命令行要指明配置文件：code --install-extension esbenp.prettier-vscode --profile 前端。
打开前端项目，点左下角齿轮，在“配置文件”里选“前端”；VS Code 记住这个文件夹用哪个配置文件。
以后从终端直接用指定配置文件打开：code . --profile 前端。
看某个配置文件里装了什么：code --list-extensions --profile 前端。

2.5 配置要点

扩展装在哪里：

范围	路径
已装扩展（Windows）	`%USERPROFILE%\.vscode\extensions`
已装扩展（macOS）	`~/.vscode/extensions`
已装扩展（Linux）	`~/.vscode/extensions`
远程端扩展	远程主机的 `~/.vscode-server/extensions`
项目推荐列表	项目里的 `.vscode/extensions.json`

扩展目录里每个扩展一个文件夹，名字是“ID-版本号”。某个扩展让 VS Code 一启动就卡死时，可以关掉 VS Code 后直接删掉它的文件夹。推荐列表要提交进仓库；扩展目录是每个人自己的，不进仓库。

.vscode/extensions.json 的最小写法：

{
  "recommendations": [                 // 打开项目时提示安装
    "EditorConfig.EditorConfig",       // 统一缩进和换行
    "esbenp.prettier-vscode",          // 格式化
    "dbaeumer.vscode-eslint"           // JS/TS 代码检查
  ],
  "unwantedRecommendations": [         // 团队不要用的，不再提示安装
    "hookyqr.beautify"                 // 会和 Prettier 抢格式化
  ]
}

和扩展有关、值得改的设置：

配置项	建议值	效果
`extensions.autoUpdate`	`true` 或 `false`	是否自动更新扩展；要锁定版本的环境设为 `false`
`extensions.ignoreRecommendations`	`false`	设为 `true` 后不再弹推荐扩展的提示
`[javascript]` 下的 `editor.defaultFormatter`	`"esbenp.prettier-vscode"`	这种语言保存时用哪个格式化器
`editor.formatOnSave`	`true`	保存时格式化
`cSpell.words`	单词数组	拼写检查不再标这些词
`http.proxy`	`"http://<代理地址>:<端口>"`	公司网络里装扩展走代理

最小配置，合并进用户设置文件（位置见 1.5）的最外层花括号里：

{
  "extensions.autoUpdate": true,                          // 扩展自动更新
  "editor.formatOnSave": true,                            // 保存时格式化
  "[javascript]": {                                       // 只对 JS 文件生效
    "editor.defaultFormatter": "esbenp.prettier-vscode"   // JS 用 Prettier
  },
  "[markdown]": {                                         // 只对 Markdown 生效
    "editor.defaultFormatter": "esbenp.prettier-vscode"   // Markdown 也用 Prettier
  },
  "cSpell.words": ["kubectl", "pyproject"]                // 拼写检查白名单
}

2.6 注意事项

装了扩展没反应，扩展视图里标“在受限模式下禁用”。 原因：没信任这个文件夹，或扩展要重新加载窗口才生效。处理：点顶部受限模式横幅上的“管理”，在打开的工作区信任页面里点“信任”；还不行就在命令面板运行“Developer: Reload Window”。
保存时格式来回变，或提示有多个格式化器可选。 原因：同一语言装了两个格式化扩展，没指定用哪个。处理：在 [语言] 下设 editor.defaultFormatter，如 "esbenp.prettier-vscode"。
VS Code 启动慢、打字卡顿。 原因：某个扩展激活或运行占用了大量时间。处理：命令面板运行“Developer: Show Running Extensions”，看耗时排前面的扩展，在当前项目里右键“禁用(工作区)”。
扩展视图报 Error while fetching extensions（中文界面是“提取扩展时出错”），或一直转圈。 原因：公司网络连不上扩展市场。处理：设置里填 http.proxy；或到市场页面下载 .vsix，运行 code --install-extension <文件>.vsix。
连上 SSH 后没有补全和跳转，扩展上提示“请在 ‘SSH: <主机>’ 中安装扩展以进行启用”。 原因：语言类扩展要装在远程端，本地装的不起作用。处理：在扩展视图里点该扩展的“在 SSH: <主机> 中安装”。
拼音变量名和专有名词底下全是蓝色波浪线。 原因：Code Spell Checker 只认英文词典。处理：在单词上按 Ctrl+.（macOS Cmd+.）选加入工作区设置，写进 cSpell.words；中文也被标时设 "cSpell.ignoreRegExpList": ["/[\\u4e00-\\u9fa5]+/g"]。
运行 code --install-extension GitHub.copilot 报 cannot be downgraded。 原因：VS Code 1.138 已内置 Copilot，市场里的旧扩展依赖的版本比内置的低。处理：不用装，点状态栏的 Copilot 图标登录 GitHub 即可。
扩展更新后功能坏了。 原因：新版有缺陷。处理：在扩展上右键“安装特定版本…“退回旧版，或运行 code --install-extension <ID>@<版本号>，再把 extensions.autoUpdate 设为 false。

2.7 深入阅读

Remote - SSH：连接服务器、配置 SSH 主机、远程端扩展的安装和排障。
扩展管理：安装、禁用、推荐列表、命令行管理扩展的官方说明。
配置文件（Profiles）：新建、切换、导出配置文件，按项目分开扩展组合。
远程开发概览：Remote - SSH、WSL、Dev Containers 的原理和入门。
工作区信任：受限模式下哪些功能和扩展会被禁用。
扩展市场：搜索、查看评分和更新记录；ID 在详情页的 Marketplace 信息里。