简介：VSCode是由微软推出的免费跨平台源代码编辑器，凭借强大的语法高亮、智能代码补全、内置Git控制等特性，已成为众多开发者首选的编码工具。针对刚开始接触这款工具的新手，这份PDF教程定位清晰：围绕下载、安装、基础配置与首个项目创建展开，帮助读者用最短时间完成从零到可用的环境搭建。内容覆盖官方下载地址与版本选择、Windows安装过程中的协议确认、安装路径设置、功能勾选等步骤，也介绍了中文语言包安装与界面切换、语言扩展浏览、项目文件夹导入等高频操作；考虑到VSCode没有内置新建项目功能，教程专门演示了如何手动新建文件夹并创建HTML文件，同时对基础优化设置和自学路径也做了简要说明。教程按安装、配置、新建项目的逻辑分步讲解，并将关键按钮与选项单列，便于学习者对照操作，有效降低试错成本。资源包共1个文件，以PDF形式打包，大小约2.12MB，适合在手机、平板或电脑上随时翻阅，目前已有1482人学习下载。
1. VSCode 下载与安装使用教程：新手卡住的从来不是编辑器本身
「VSCode 下载与安装使用教程」这类文档满天飞，可我见过太多人看完仍然装不上、用不明白：下载页全英文不知道点哪个，安装时一路 Next 结果右键菜单里找不到“通过 Code 打开”，装完想写 C++ 却发现连代码提示都不出来。真正卡住新手的，往往不是 VSCode 本身，而是下载入口、版本选型、安装选项这三个环节里没人讲透的细节。这篇教程就是来补这些细节的：从官网下载入口开始，到安装选项怎么勾，再到汉化、C/C++ 与 Python 环境配置，最后是五条高发踩坑记录。适合第一次接触代码编辑器、准备在 Windows 上搭开发环境的人，也适合刚被“代码无法跳转”这类问题劝退的初学者。
先别急着下载，版本选错了后面全是坑。
2. 先选对版本再下手：User / System / 便携版与安装选项
2.1 三种版本的区别：同一个安装包，行为完全不一样
VSCode 官网只提供一个安装包，但双击之后你会在安装类型里看到“按用户”和“系统安装”两个选项，外加官网单独提供的 ZIP 便携版。很多人不知道这三者的差异，装完才发现权限、PATH、扩展目录全不对。
- User 模式（默认，推荐）：安装到
%USERPROFILE%\AppData\Local\Programs\Microsoft VS Code。不需要管理员权限，所有配置和扩展写在自己的用户目录下。适合公司电脑、共享电脑、或者你不想动不动就 UAC 弹窗的情况。 - System 模式：安装到
C:\Program Files\Microsoft VS Code。需要管理员权限，装完后所有 Windows 用户都能用同一个编辑器。缺点是扩展、配置会写在用户级目录里，多人共用时容易互相污染；而且每次升级都要求管理员权限。 - ZIP 便携版：官网下载页有个“.zip”压缩包选项。解压后把
data文件夹放在 VSCode 的根目录下，编辑器会自动把配置、扩展、缓存全部收进data里。我一般用它在 U 盘里做一个“随身开发环境”，换台电脑插上 U 盘就是同一套配置，不往系统里写任何东西。
选型的判断标准很简单：自己一个人用选 User；需要给整个系统所有账户提供编辑器选 System；要在不同电脑之间带着走，或者不想让 VSCode 在系统里留痕迹，选 ZIP 便携版。版本选错不是不能用，但后面每一条路径、PATH、右键菜单都会出问题，排查起来非常费时。
2.2 下载入口怎么认：认准官网，不认“高速下载”
现在搜“vscode 官网下载”，前几条不一定是官网。判断正统入口的方法只有一个：看域名是不是code.visualstudio.com。进到官网后首页就有蓝色的下载按钮，Windows 用户选Windows x64 User Installer即可。
如果你在官网只看到 “Debian/Ubuntu”“macOS” 这些选项，说明页面识别错了系统，手动切到 Windows 标签就行。还有一种常见迷惑：下载按钮显示.zip和.exe两种格式，.exe是向导安装，.zip是便携版。第一次用的人直接选.exe最省事。
下载完成拿到的是一个几十到上百 MB 的安装程序，不同版本体积有差异，不用惊讶。安装包运行之后首页会要求接受协议，这时先不要急着点“下一步”，看下面几个关键选项。
2.3 安装向导里必须勾选的四个选项（及参数含义）
网上很多教程让你“一路 Next”，但微软官方安装选项里有几项默认不勾选，对后续使用影响极大。下面是安装到选择附加任务这一步时，我建议的设置：
| 安装选项 | 是否勾选 | 说明 |
|---|---|---|
| 将“通过 Code 打开”操作添加到 Windows 资源管理器目录上下文菜单 | 勾选 | 否则在文件夹上右键没有“通过 Code 打开”，这是新手第一个困惑 |
| 将“通过 Code 打开”操作添加到 Windows 资源管理器文件上下文菜单 | 勾选 | 单独文件右键也能快速打开 |
| 将“code”注册为受支持文件类型的编辑器 | 建议勾选 | 让常见文本文件默认用 VSCode 打开 |
| 添加到 PATH | 勾选 | 安装后可以在终端里直接敲code .打开当前目录，这也是大量教程的前提 |
| 在安装时创建桌面快捷方式 | 按个人习惯 | 不影响功能 |
这里最容易翻车的是“添加到 PATH”。如果安装时没勾选，哪怕 VSCode 装好了，在 PowerShell 里输入code .会直接报“code 不是内部或外部命令”。解决方式有两种：重装时勾选，或者手动把安装目录加入系统环境变量。我一般会直接改环境变量，路径填 VSCode 安装目录下的bin文件夹，比如C:\Users\你的用户名\AppData\Local\Programs\Microsoft VS Code\bin。
2.4 静默安装的参数：适合批量部署和团队统一版本
如果你在给团队配统一开发环境，或者不想手动点安装向导，可以用命令行静默安装。VSCode 的安装包基于 Inno Setup，支持以下参数：
"C:\Users\你\Downloads\VSCodeSetup-x64-最新版本.exe" /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /SP- /MERGETASKS=!runcode,addcontextmenufiles,addcontextmenufolders,associatewithfiles,addtopath逐项说明：
/VERYSILENT：安装过程不显示任何界面，全程后台执行。/SUPPRESSMSGBOXES：抑制安装过程中的弹窗提示，避免卡在某个需要人工确认的对话框上。/NORESTART：安装结束后不重启电脑。/SP-：跳过“准备安装”时的许可确认页面。/MERGETASKS：任务项合并控制，这里的addcontextmenufolders和addtopath正好对应刚才说的“右键菜单”和“PATH”两个关键项。名字前面加!表示排除该任务，比如!runcode表示不额外运行 VSCode。
这条命令适合做装机脚本的一部分。执行完验证方式很简单：新开一个终端窗口，输入code --version，能输出版本号就说明装成功且 PATH 生效了。
2.5 便携版的手动落地方案
如果你选了 ZIP 便携版，落地步骤是：解压后进入VSCode-win32-x64文件夹，在文件夹里新建一个名为data的目录，然后再启动Code.exe。有data目录时，VSCode 会进入便携模式，界面左下角会出现齿轮图标，当前实例的用户数据目录变为data\user-data，扩展目录变为data\extensions。
一个容易忽略的点：便携版的配置不走系统临时目录，也不会和 User 模式互相污染。所以如果要维护多套独立环境，这是最好的隔离方式。缺点也有——后续升级需要重新下载 zip 覆盖，扩展也全部重新下载，首次启动会慢一些。
3. 装完先做三件事：汉化、settings.json 与配置同步
3.1 汉化不是装完就能用：语言包与 locale 设置
VSCode 默认界面是英文，热词里“vscode 汉化”“vscode 设置中文”搜索量一直很高。汉化不是改语言选项，而是要安装一个语言扩展：打开扩展面板（快捷键Ctrl+Shift+X），搜索Chinese，安装 “Chinese (Simplified) (简体中文) Language Pack”。安装后右下角会弹窗提示重启，重启后界面即变中文。
用命令行也可以：
code --install-extension ms-ceintl.vscode-language-pack-zh-hans执行后重启 VSCode。如果界面仍是英文，检查右下角语言模式或者用Ctrl+Shift+P打开命令面板，输入Configure Display Language，确认里面选的是zh-cn。这一步经常被忽略：语言包装了，但locale没切，界面就是不变。
3.2 三个进 settings.json 就该改掉的默认值
打开设置：Ctrl+Shift+P，输入open settings json，选择 “首选项：打开用户设置(JSON)”。以下三个配置对日常开发体验影响最大：
{ "files.autoSave": "afterDelay", "editor.formatOnSave": true, "editor.tabSize": 4, "files.eol": "\n", "workbench.startupEditor": "none", "files.hotExit": "onExitAndWindowClose" }参数含义：
files.autoSave：设为afterDelay后，停止输入约 1 秒自动保存，不用再手动Ctrl+S。默认官方的行为是关闭自动保存，新手经常写了一半去切窗口，回来发现改动丢了，就是这个值没设。editor.formatOnSave：保存时自动格式化当前文件。配合 C/C++、Python 扩展，可以在保存瞬间统一缩进、空格、换行风格。前提是你已经安装了对应语言的格式化扩展，否则保存时会报“没有已注册的格式化程序”。files.eol：设为\n（LF）能避免 Git 仓库里出现大量CRLF与LF混用的 diff。Windows 默认行尾是CRLF，如果团队成员有 Linux/macOS，这一个配置能省掉很多无谓的冲突提示。
files.hotExit是很多人不注意但也值得设的一项：它控制关闭窗口时未保存文件的去留。设置成onExitAndWindowClose后，关掉整个窗口时 VSCode 会像“休眠”一样保留未保存的文件，下次打开还在。后面避坑章第一条会专门展开这个设置引出的现象。
3.3 工作区 vs 全局设置：区分这两个，才能一人一套配置
VSCode 里有两层主要设置：用户设置（全局默认）和工作区设置（只对当前打开的文件夹生效）。配置位置分别是用户设置 JSON 和工作区根目录下的.vscode/settings.json。
常见做法是：通用体验类配置（自动保存、字号、主题）放用户设置；与项目强相关的配置（编译器路径、Python 解释器、格式化规则）放.vscode/settings.json。这样换项目时不会互相影响，也能通过.vscode目录随项目走，团队新成员拉下代码就有同样的编辑器行为。
区分这两个配置还有一个实际好处：当项目里的.vscode/settings.json配置和你的全局配置冲突时，工作区配置优先。遇到“换了个项目，编辑器行为全变了”这类问题，第一步就该看项目里有没有.vscode目录。
3.4 换机不重建：官方设置同步怎么开
热词里有大量“vscode 配置 claude code”“vscode 配置 kimi”这类关键词，说明大家已经意识到扩展和 IDE 配置是高度自定义的资产，换机重配很痛苦。VSCode 官方提供了“设置同步”功能，不需要第三方插件：点击左下角齿轮，选择“打开设置同步”，登录微软账号或 GitHub 账号，然后勾选要同步的项——设置、键盘快捷键、扩展、UI 状态。
同步是按账号走的，换新机器后登录同一账号，在新机器上执行一次“同步”即可恢复关联的数据。两个机器同时开着同步时偶尔有冲突提示，此时选择“合并”或“用本地替换”都行，一般建议看哪边的扩展列表更完整，选保留完整的那边。
也有团队不放心账号同步，更倾向把配置固化成文件：用命令行code --list-extensions > extensions.txt导出已装扩展 ID 列表，新机上执行code --install-extension < extensions.txt批量安装。这个思路我在最后一章会用作进阶技巧展开，因为它比账号同步更适合离线环境和团队统一版本。
4. 配好 C/C++ 与 Python 语言环境：编译、调试与智能提示
4.1 C/C++ 环境：从“能跑”到“能跳转”只需两件套
热词里“vscode 配置 c/c++ 环境”“vscode c++ 所有的函数变量都没办法跳转”反复出现，说明大部分人的问题不在编译，而在语言服务的配置。第一次在 Windows 上跑 C++，核心是两件事：编译工具链和 VSCode 的 C/C++ 扩展。
编译工具链目前最常见的选择是 MinGW-w64。下载后把bin目录（里面有gcc.exe）加入 PATH，在终端验证：
gcc --version能输出版本信息说明工具链就绪。然后在 VSCode 里安装 Microsoft 官方扩展：C/C++（发布者是 Microsoft）。扩展的作用不是编译，而是提供 IntelliSense 代码提示、跳转定义、悬停文档和调试支持。
安装完扩展后，还需要一份c_cpp_properties.json告诉语言服务编译器在哪。在命令面板执行C/C++: Edit Configurations (JSON)，一般生成如下内容：
{ "configurations": [ { "name": "Win32", "includePath": ["${workspaceFolder}/**"], "defines": [], "compilerPath": "C:/MinGW/bin/gcc.exe", "cStandard": "c17", "intelliSenseMode": "windows-gcc-x64" } ], "version": 4 }参数说明：
includePath：告诉 IntelliSense 到哪些目录找头文件。${workspaceFolder}/**表示当前工作区及子目录都算进来。compilerPath：必须指向真实存在的编译器路径。如果编译器没加入 PATH，这里又写错路径，代码提示会彻底罢工。intelliSenseMode：windows-gcc-x64对应 Windows 下用 GCC 工具链；如果用的是 MSVC，则改为windows-msvc-x64。这个模式对不上，会出现“明明编译器能用，但代码标红一片”的怪象。
4.2 一键编译与调试：tasks.json 和 launch.json 的接线
有了编译器和扩展，还要把“一键编译”跑起来。VSCode 本身不负责编译，它通过任务（task）调用外部命令。在项目根目录建.vscode/tasks.json：
{ "version": "2.0.0", "tasks": [ { "label": "C++ 编译当前文件", "type": "cppbuild", "command": "g++", "args": [ "-g", "${file}", "-o", "${fileDirname}/${fileBasenameNoExtension}.exe" ], "group": { "kind": "build", "isDefault": true } } ] }逻辑说明：command是要执行的程序，args是传给它的参数。${file}是当前打开的源码文件，${fileDirname}是所在目录，${fileBasenameNoExtension}是去掉扩展名的文件名。所以hello.c会被编译成同目录下的hello.exe，带-g参数保留调试信息。
按下Ctrl+Shift+B执行编译任务后，如果终端显示编译成功，但按F5想调试却报了 “无法找到调试程序”，那是因为还缺launch.json：
{ "version": "0.2.0", "configurations": [ { "name": "C++ 调试", "type": "cppdbg", "request": "launch", "program": "${fileDirname}/${fileBasenameNoExtension}.exe", "args": [], "stopAtEntry": true, "cwd": "${fileDirname}", "environment": [], "externalConsole": false, "MIMode": "gdb", "miDebuggerPath": "C:/MinGW/bin/gdb.exe" } ] }两个文件之间靠程序路径和编译产物路径对接：tasks.json编译到哪，launch.json的program就必须指向哪个可执行文件。大多数人调试失败就是这里不一致——编译产物在build子目录，调试配置却指向根目录。stopAtEntry设为true会在进入main时暂停，方便看启动过程，等熟练后可以改成false。
如果用的是 clangd 做智能提示，需要注意它和 Microsoft C/C++ 扩展会抢代码提示通道。常见做法是二选一：用 clangd 就把 C/C++ 扩展关掉或禁用对当前工作区的支持，否则会出现两个提示框打架、跳转时而灵时不灵的症状。clangd 需要compile_commands.json作为编译数据库，对纯手写 Makefile 的小项目配置成本偏高，新手阶段我更建议直接用 Microsoft 官方扩展。
4.3 Python 环境：先建虚拟环境再选解释器
配置 Python 环境时，很多教程直接让你装 Python 扩展就完事，但实际开发中还有一道关键链路：虚拟环境与解释器选择。
python -m venv .venv在项目根目录执行这条命令，会创建一个独立的.venv目录。为什么要先做这一步？因为直接用全局 Python 装包容易把系统环境搞乱，而且不同项目依赖版本互相冲突。虚拟环境把依赖隔离在项目内部，是后续所有 Python 开发的基础。
接着在 VSCode 里安装Python扩展（发布者为 Microsoft）。安装完成后，Ctrl+Shift+P输入Python: Select Interpreter，选择刚才创建好的.venv目录下的解释器。VSCode 会读取该解释器下的包列表来提供智能提示，选错解释器时最明显的症状是：代码里已经pip install过的包依然标红、无法补全。
在.vscode/settings.json里固定解释器路径是一个更稳的做法：
{ "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe", "python.testing.pytestEnabled": true, "python.testing.unittestEnabled": false }python.defaultInterpreterPath写成工作区路径后，以后在新目录打开项目时不会再“找不到解释器”。pytestEnabled开启后，测试文件旁边会出现 ▶ 按钮，直接单测某个函数。顺便说一句，热词里的“vscode 查看函数参数 python”，其实不需要额外扩展：把鼠标悬停在函数名上，或者把光标移到函数括号内按Ctrl+Shift+Space，就能看到完整的签名和文档。
4.4 远程开发：Windows 本地写代码，Linux 环境里跑
热词里有“在 vscode 中使用 wsl”，这属于远程开发的正规场景。如果你在用 WSL 里的 Linux 环境编译、跑服务，本地 Windows 上的 VSCode 只是编辑器，真正的工具链在 WSL 内部。
做法是：安装Remote-WSL扩展，然后用Ctrl+Shift+P执行Remote-WSL: New Window，VSCode 会重新以 WSL 身份加载当前目录。此时左下角会出现 “WSL: Ubuntu” 之类的标识，集成终端也自动进入 Linux 环境，可以直接敲gcc、python3，无需在 Windows 侧再配一遍编译器。配合 SSH 场景时，Remote-SSH扩展是同一套用法——本地编辑、远端编译调试，代码不落本地。
易错点：在 WSL 窗口里装插件要重新装一遍，Windows 侧的扩展不会自动被 WSL 复用。有些扩展体积大、需要本地 GUI，就不适合在远程环境安装；建议远程环境只装语言支持和调试类扩展，把主题、工具类扩展留在本地。
5. 新手最容易踩的 5 个坑：现象、原因与解决
5.1 一个都没改的文件，关掉窗口后内容“消失了”
现象：新建文件随便敲了几行没保存，直接点了关闭窗口，下次打开提示里没有这个文件，文件真不见了。网上常描述为“没有编辑的文件会关上”。
原因：VSCode 对“已修改但未保存”和“打开后未做任何编辑”两种文件处理不同。未修改的文件默认不会触发保存提示，直接关闭窗口后就没了。很多刚入门的人把这里误认为数据丢失。
解决：在settings.json里把files.hotExit设为onExitAndWindowClose，并保持workbench.startupEditor为none，然后开启files.autoSave: afterDelay。三管齐下后，正常输入的内容基本都能找到。如果已经丢了，入口是“文件”面板的“打开最近的文件”里看看有没有本地历史：Ctrl+Shift+P执行File: Revert File只能回退到磁盘版本，真正的救急功能是“本地历史”，在时间线面板里可以看到每次保存前的版本。
5.2 文件夹右键没有“通过 Code 打开”
现象：VSCode 装好了，双击.c文件也能打开，但资源管理器里右键文件夹没有任何 VSCode 选项。
原因：安装向导里“添加到资源管理器上下文菜单”两项没有勾选。奇怪的是，VSCode 升级后偶尔也会出现右键菜单丢失，原因不确定，但和安装时勾选的注册表项被安全软件清理有关。
解决：首选手动修复。重新运行 VSCode 安装程序，选择“修改”，把上下文菜单相关项重新勾上。如果安装程序已删，就用安装时下载的安装包再跑一次。对个别安全软件清理导致的问题，重新覆盖安装基本都会恢复。
附带一个终端替代方案：在任意文件夹的地址栏输入cmd回车，在弹出的终端里执行code .。这个命令把当前目录作为工作区打开，效果等同右键菜单。前提是安装时勾选了“添加到 PATH”，这再次说明 2.3 节那几个勾选项有多关键。
5.3 C++ 代码无法跳转定义 / 所有函数变量都找不到引用
现象：写 C++ 时点击函数名按F12，界面没有任何反应或者提示“找不到定义”。函数、变量全部无法跳转，代码提示也几乎为空。
原因：最常见的是语言服务没有起来。Microsoft C/C++ 扩展需要知道编译器路径和头文件目录，如果编译器没装、compilerPath写的路径不存在，IntelliSense 会直接罢工且不报错。另一种情况是 clangd 和 C/C++ 扩展同时启用，两个语言服务抢同一份代码索引，跳转结果时好时坏。
解决：先检查右下角状态栏的语言模式，确认是C++而不是Plain Text。然后打开c_cpp_properties.json，确认compilerPath指向存在且正确的编译器，比如C:/MinGW/bin/gcc.exe。如果用了 clangd，打开命令面板执行clangd: Restart language server并等待左下角显示“索引完成”；若两个扩展同时存在，建议在.vscode/settings.json里禁用其中一个对当前工作区的服务。
5.4 项目一打开风扇狂转，资源管理器卡死
现象：打开一个比较大的前端或嵌入式工程，VSCode 占用 CPU 居高不下，编辑器卡顿，有时还会报“Visual Studio Code 占用的内存过高”。
原因：VSCode 默认会监视工作区下所有文件的变化。node_modules、build、.git目录里的文件数量惊人，文件监视器被塞满后不仅卡，还会触发 CPU 持续高占用。
解决：在.vscode/settings.json里明确排除这些目录：
{ "files.watcherExclude": { "**/node_modules/**": true, "**/build/**": true, "**/.git/**": true }, "search.exclude": { "**/node_modules/**": true, "**/build/**": true }, "files.exclude": { "**/build/**": true } }files.watcherExclude控制文件监视器不去监听哪些目录；search.exclude控制全局搜索跳过哪些目录；files.exclude让资源管理器里不显示这些目录。三者各管一段，建议一起配好。配完重启一次 VSCode，风扇问题基本立竿见影。
5.5 终端与调试输出中文乱码，跑 Java 报乱码
现象：Windows 上终端调用g++编译，报错信息里的中文全部显示成乱码；跑 Java 时控制台输出中文变成“锟斤拷”。
原因：Windows 控制台默认代码页是 936（GBK），而 VSCode 的终端和很多现代工具默认输出 UTF-8。两边编码不一致，中文自然乱码。
解决：在.vscode/settings.json里为终端指定 UTF-8 启动参数：
{ "terminal.integrated.profiles.windows": { "PowerShell": { "path": "powershell.exe", "args": ["-NoExit", "-Command", "chcp 65001"] } }, "terminal.integrated.defaultProfile.windows": "PowerShell" }chcp 65001是切到 UTF-8 代码页的命令，-NoExit防止执行完直接关掉终端。Java 场景额外在.vscode/settings.json里加一项"java.debug.settings.console": "integratedTerminal"，避免 Java 调试控制台自己走一套编码。改完配置需要新开终端，旧的终端不会自动刷新代码页。
6. 最后一招：把环境固化成文件，换机十分钟还原
前面讲了很多配置，但配置这东西一旦重装系统、换新电脑，就要全部重来。我现在的习惯是：以“文件快照”为中心维护一套可移植的配置，账号同步只是备用。这一招叫“环境固化”，核心是两份文件加一条命令。
一份是扩展列表。在配好环境的机器上执行：
code --list-extensions > extensions.txt导出的文件长这样：
ms-ceintl.vscode-language-pack-zh-hans ms-python.python ms-vscode.cpptools每一行是一个扩展的唯一 ID。换机后只需执行：
code --install-extension < extensions.txt<是重定向，把文件内容逐行当成参数传给命令，Linux 和 Windows PowerShell 均支持。执行完新机器的扩展就和你原来的环境一致了。这条命令比账号同步可靠的地方在于：它不依赖登录状态，离线也能跑，也方便你自己控制版本。
另一份是.vscode/settings.json，把用户设置里那些“非它不可”的配置整理出来，放到一个公共目录或 Git 仓库里。换机后先把文件放到用户配置目录，再手动合并掉个人偏好的主题字号部分即可。完整的做法还可以把键位绑定keybindings.json一并纳入。这样不管换机还是帮同事搭环境，十分钟就能回到熟悉的状态。
最后补一个容易被人忽略的验证方法：装完环境后故意把一个带错误的 C++ 文件编译一次，确认报错信息能定位到具体行；再打开一个类定义跳转一次，确认语言服务正常。验证步骤跑通过一遍，这个环境才算真正立住了。我自己每次重装后第一件事就是跑这两个验证，而不是打开编辑器看界面变没变。希望帮到你。
本文还有配套的精品资源，点击获取
