简介《VSCode下载与安装使用教程》PDF面向零基础编程学习者、转行人员及需要统一开发环境的教学场景重点解决编辑器获取、安装配置与初步使用中的常见障碍。资源包仅含1个PDF文件大小约2.12MB轻量便于保存和随查随用。内容围绕VSCode简介、官方下载入口、安装向导选项、中文语言包与语言插件安装、基础设置以及手动新建项目文件夹等展开并对手动建项目这一新手易困惑环节作了说明。读者可据此快速完成开发环境搭建理解扩展插件与设置项的作用减少因路径选择、语言切换和项目导入不当产生的重复试错也可作为课堂或培训的辅助材料。目前已有1496人学习。1. 装 VSCode 最容易出问题的不是安装过程而是第一个终端命令第一次装 VSCode十有八九会在最后一屏犹豫三秒安装向导问要不要“添加到 PATH”勾不勾看上去都行。等到第二天在项目目录里敲code .终端回一句“不是内部或外部命令”才发现当初没勾的那个框才是关键。VSCode 下载与安装这套流程本身不复杂官方安装包一路下一步就能装完问题出在版本选择上32 位还是 64 位、ARM 还是 x86、用户级还是系统级安装选错了不会报错但会在扩展、命令行、多用户共用这些地方逐渐造成问题。这篇不是功能介绍是一份从下载、逐屏安装、首次配置到装坏了怎么救的完整记录。刚换电脑搭前端环境的、要给实验室机器批量装的、以及装过一次但code命令至今没跑通的都能按顺序照做。整条路线走完大概二十分钟验证通过之后环境搭建这件事就算告一段落。2. 下载与版本选择四类安装包对着人群选打开官方下载页默认给你的是当前稳定版一个大按钮写着 Download for Windows。很多人到这一步就点了但其实按钮右边的下拉箭头里藏着 Linux、macOS 和不同架构的包选错架构的后果不是装不上是装上了但扩展跑不动、调试器起不来排查起来反而更难。2.1 下载页的入口分别对应哪些用户官方下载页的结构按我的经验可以分三层看第一层是主按钮它根据你当前访问设备的系统自动推荐。在 Windows 上就是 Windows 版在 macOS 上就是 macOS 版。这个按钮给的是 64 位 x86 版本绝大多数人可以直接用。第二层是主按钮旁边的下拉展开后能看到 macOS、Linux 的完整清单。macOS 要分清 Intel 芯片和 Apple Silicon 两套包2020 年之后的机器基本都是后者装错了会提示“需要 Rosetta”或者直接打不开。Linux 则是.deb、.rpm、.tar.gz三种格式分别对应 Debian/Ubuntu 系、Fedora/RHEL 系、以及不想走包管理器的场景。第三层是页面上的 Insiders 版本入口。这是每日构建版新特性先上但稳定性没保证。我一般只在一台不干活的机器上装 Insiders专门用来提前发现扩展兼容问题主力开发机上从来不用。系统包格式适用对象备注Windows x64.exe绝大多数 PC分用户级与系统级Windows ARM64.exe骁龙本等 ARM 设备架构不对会跑成模拟macOS Intel.zip老款 Mac解压即用无安装向导macOS Apple Silicon.zipM 系列芯片别下错Linux Debian 系.debUbuntu、Debiandpkg 安装Linux RedHat 系.rpmFedora、RHELrpm 安装Linux 通用.tar.gz无 root 权限解压后手动建软链需要说明的是Windows 上还有一个网页版入口浏览器直接打开就能编辑代码。它适合临时改一两个文件但本地调试、终端、大部分依赖本地运行环境的扩展都用不了。把它当成应急工具别当成安装替代方案。2.2 用户级安装与系统级安装一次选错后面全在补救Windows 安装包实际上分两种下载页上写的是 User Installer 和 System Installer。名字很朴素差别却直接影响后面的使用体验这是最容易选错的地方。用户级安装装到当前用户目录下全程不需要管理员权限自动更新也是静默的。系统级安装要管理员权限装在公共的程序目录里机器上所有账号都能用。维度用户级系统级管理员权限不需要需要安装位置当前用户目录系统程序目录多账号共用不能能自动更新默认开启无需提权需要提权可能被策略拦住卸载残留少跟着用户目录走需手动清理公共目录适合场景个人电脑、公司配的开发机实验室公用机、机房我一般建议个人开发机一律用用户级。原因很实际公司电脑经常没有管理员权限系统级安装到一半被拦截残留一堆临时文件重装还会提示“已存在同版本”。系统级只在两种情况下值得用一是这台机器要多人登录共用二是内网有统一的软件分发策略要求装在固定路径。提示用户级和系统级不能混装在同一台机器上。混装之后会出现两个版本、两个卸载项、PATH 里指向其中一个扩展却装在另一个的用户目录里症状是“扩展明明装了但不生效”。2.3 下载完先校验别急着双击安装包从浏览器下来中间可能被下载器、公司网络策略拦过。养成习惯下载完先算一遍哈希和官方发布的校验值对一下。Windows 用自带的certutil就行# Windows计算安装包的 SHA256 certutil -hashfile .\VSCodeSetup-x64.exe SHA256 # macOSzip 包同样适用 shasum -a 256 ~/Downloads/VSCode-darwin.zip # Linuxdeb/rpm 用 sha256sum sha256sum ./code_amd64.deb三条命令做的事一样都是对文件做 SHA-256 摘要。-hashfile后面跟文件路径最后那个参数是指定算法不写默认也是 SHA256但明确写出来更稳妥。算出来的字符串和官方下载页给出的校验值逐位比对一位不对就别装重新下载。这一步在个人电脑上看起来多余但在内网分发、离线拷贝、U 盘传递的场景下非常值得。文件通过多层转手损坏和被替换的概率不低装完出现一些奇怪的崩溃回头怀疑是代码问题时其实安装包本身就是问题的根源。另外提前说一下离线场景。有些机器完全不能上网但需要装扩展。做法是先在能上网的机器上下载.vsix扩展包拷过去用命令行安装这一点在第 4 章展开。3. 安装向导逐屏操作五个勾选框决定后面省不省事双击安装包之后是一串向导页绝大多数人到这里就是一路“下一步”。真正需要停一下的只有三处安装路径、附加任务勾选、以及装完之后的命令验证。这一章按屏幕顺序过一遍每屏说清楚为什么这么选。3.1 许可协议、安装路径与开始菜单第一屏是许可协议勾选“我同意此协议”才能继续。这一屏没什么可讲的点下一步。第二屏是安装路径。默认路径在系统盘的用户目录或程序目录下具体取决于你装的是用户级还是系统级。我的习惯是改到非系统盘比如D:\Tools\VSCode。这么做有两个理由一是系统盘空间紧张时扩展缓存和用户数据会越滚越大一个常年写前端的人扩展目录涨到几个 G 很常见二是重装系统时如果保留了数据盘配置可以整套带走。路径上有两点要注意。第一别用中文路径也别在路径里放空格。VSCode 本体能处理但某些扩展调起外部工具链时会因为路径解析出错症状是“调试器启动失败”或者“找不到编译器”日志里翻半天才看到路径被截断。第二路径别选太深Windows 有 260 字符的路径长度限制node_modules 那种嵌套目录很容易撞上。第三屏是开始菜单文件夹名默认就是产品名一般不用改。如果机器上同时装了多个版本做对比测试可以在这里加后缀区分比如加个-Insiders或者-Test省得点错。3.2 附加任务勾选五个框我勾哪几个这一屏是整个安装过程中最值得花两分钟的地方。五个复选框逐个说第一个是创建桌面快捷方式。看个人习惯我用开始菜单和Win键搜索更多桌面基本不勾保持干净。第二个是把“通过 Code 打开”加到文件的右键菜单。这个我必勾。写脚本、改配置、看 JSON 的时候右键直接打开比先开编辑器再找文件快得多。第三个同样是右键菜单但加在文件夹上。这个也必勾而且比第二个更常用。原因在于 VSCode 的使用方式是“打开文件夹”右键一个项目目录直接打开是最顺手的工作流。第四个是把编辑器注册为受支持文件类型的默认打开方式。这个要谨慎。勾了之后.txt、.log这类文件可能都被改成用 VSCode 打开系统里原本的记事本、日志查看器会被抢走。我通常不勾需要的时候再在系统设置里单独指定。第五个是添加到 PATH也就是开头说的那个关键框。这个必须勾勾了之后才能在任意终端目录下敲code。注意向导上通常写着“重启后生效”意思是已经打开的终端窗口读的是旧的环境变量不是让你真去重启电脑——关掉终端重开一个就行。勾选项建议影响创建桌面快捷方式可选只是多一个图标添加到文件右键菜单勾单文件快速打开添加到目录右键菜单勾项目目录快速打开注册为文件类型编辑器不勾会抢走系统默认关联添加到 PATH勾code命令可用勾完点下一步确认页会列出安装位置和勾选项扫一眼没问题就点安装。整个过程通常不到一分钟。3.3 装完先验 code 命令别等出问题再回头安装程序结束页有个“运行”复选框会直接拉起编辑器。先别急着点打开一个终端把命令验一遍# 查看版本号能输出说明可执行文件在 PATH 里 code --version # 查看帮助确认子命令齐全 code --help # 查一下命令实际指向哪个路径 # Windows where code # macOS / Linux which codecode --version会打印三行第一行是版本号第二行是提交哈希第三行是 CPU 架构。架构这一行值得看一眼ARM 机器上如果显示的是 x64说明装成了模拟版本性能会打折扩展也可能不兼容。where和which是找命令实际位置的输出应该指向你刚才设置的安装目录。如果输出为空或者报“找不到”说明 PATH 没生效。先关掉终端重新打开一个再试还不行就是安装时漏勾了这时候不用重装在安装包里选择修复或修改重新勾一次 PATH 更省事。再补一个常用命令用手动方式打开当前目录# 在项目目录下执行直接以该目录作为工作区启动 code .点号代表当前目录。这条命令后面会反复出现它是 VSCode 使用方式的核心——不是打开一个文件而是打开一个文件夹作为工作区。4. 首次启动配置中文语言包、扩展与设置文件第一次启动会看到一个欢迎页左边是最近打开的项目右边是一堆引导入口。这些引导可以先跳过按下面的顺序把三件事做完环境就算配置好了换成中文界面、装扩展、改设置。4.1 中文语言包装了没变中文的两个原因默认界面是英文的。换成中文有两种做法一种走图形界面一种走命令行。图形界面的做法是打开命令面板快捷键CtrlShiftPmacOS 上是CmdShiftP输入“display”找到“Configure Display Language”这一项列表里如果有中文就选没有就点“Install Additional Languages”会跳到扩展面板并自动筛选语言包找到简体中文那一项点安装。命令行更适合批量部署或者远程机器# 安装简体中文语言包扩展 ID 在扩展详情页可以复制 code --install-extension 语言包扩展ID # 列出已经装上的扩展确认装成功了 code --list-extensions--install-extension后面跟的是扩展的唯一标识不是显示名称。这个标识在扩展详情页的右侧能直接复制格式通常是“发布者.扩展名”。--list-extensions会按字母序列出所有已安装扩展的标识用来核对很方便也可以配合--show-versions看版本号。装完右下角会弹窗提示重启点重启之后界面就是中文了。如果重启后还是英文八成是这两个原因一是装成了别的语言包扩展市场里同名不同语言有好几个别按首字母顺手点。二是 locale 没写进去。旧版本通过locale.json控制新版本统一放在用户目录下的argv.json里文件里应该有一行locale: zh-cn。这个文件可以用命令面板里的“Configure Runtime Arguments”直接打开改完完全退出编辑器再启动注意是完全退出不是关窗口——macOS 上关窗口进程还在要CmdQ。4.2 扩展市场与离线 vsix 安装扩展面板在左侧活动栏图标是四个方块。搜索框输入语言名或工具名右侧列表会按相关度排序。新手容易在前端项目里装十几个扩展导致启动变慢其实真正需要常备的没那么多——语言支持、格式化、Git 相关的装几个就够其余按项目需要再加。装扩展有三个入口按场景选图形界面搜索安装最直观适合在家里的机器上慢慢挑。命令行安装适合写进部署脚本一条命令批量装完重装系统时把清单存成文件直接跑。第三种是.vsix离线包用在完全断网的机器上。离线安装要先在能上网的机器上把扩展打包下来。扩展详情页的齿轮菜单里有“下载 VSIX”选项下下来的文件拷到目标机器然后# 从本地 vsix 文件安装扩展 code --install-extension ./some-extension.vsix # 批量安装时循环处理目录下的所有 vsix for f in ./extensions/*.vsix; do code --install-extension $f; done第一条命令指定单个文件路径可以是相对路径也可以是绝对路径。第二条是 Linux/macOS 上的循环写法把目录下所有 vsix 挨个装一遍Windows 的命令行语法不同得用for %f in (*.vsix) do code --install-extension %f。批量装的时候注意扩展之间的依赖有的扩展会依赖另一个扩展提供的接口顺序错了会提示缺少依赖重跑一遍通常就好。扩展装多了想看谁在拖慢启动可以用code --status。它会打印当前运行的进程、内存占用和已激活的扩展找出那些常驻的大块头不用的禁用掉。4.3 settings.json我每次都会改的几行图形化的设置页面能覆盖大部分需求但真正好用的还是直接改配置文件。命令面板里搜“Open User Settings (JSON)”打开的就是它。这个文件虽然是.json后缀但实际是支持注释的 JSONC 格式写注释不会报错这点和普通 JSON 不一样。{ // 字号和缩进按自己屏幕调 editor.fontSize: 15, editor.tabSize: 2, // 保存时自动格式化需要装了对应语言的格式化扩展才生效 editor.formatOnSave: true, // 焦点离开编辑器时自动保存比定时保存更可控 files.autoSave: onFocusChange, // 统一换行符避免跨系统协作时整文件 diff files.eol: \n, files.encoding: utf8, // 关掉缩略图小屏幕能多出两行代码 editor.minimap.enabled: false, // 显示行尾空格和制表符方便发现格式问题 editor.renderWhitespace: boundary, // 启动时不显示欢迎页 workbench.startupEditor: none, // 删除文件时不弹确认框误删可以用 Git 恢复 explorer.confirmDelete: false }逐条说一下取舍。editor.tabSize设成 2 是前端项目的常见约定写 Python 的话改成 4。files.autoSave选onFocusChange而不是afterDelay是因为定时保存容易在敲一半的时候触发格式化把没写完的语句搅乱。files.eol统一成\n在 Windows 上尤其重要否则和 Linux 上的同事协作时每个文件都会显示整文件改动。editor.formatOnSave依赖具体语言的格式化器纯 HTML、CSS、JSON 有内置的JavaScript、Python 需要额外装扩展没装的时候这一行不生效也不报错容易让人以为是设置写错了。还有一个跟版本有关的点终端默认配置项在不同版本里名字变过。老版本写terminal.integrated.shell.windows新版本已经废弃改成了terminal.integrated.defaultProfile.windows值是PowerShell、Command Prompt这类配置文件名。如果你从旧机器上抄了一份配置过来发现终端设置不生效多半就是这一行在旧版本里的写法。4.4 新建项目其实是新建文件夹这是新手最容易困惑的地方别的编辑器有“新建项目”菜单VSCode 没有。原因在于它的工作区模型——一个文件夹就是一个工作区不需要项目文件来定义。所以所谓新建项目就是手动建一个目录再打开。# 建项目目录并进入 mkdir demo-site cd demo-site # 以当前目录为工作区启动编辑器 code .两条命令第一条创建目录并切换进去第二条把当前目录交给编辑器。窗口标题栏会显示目录名左侧资源管理器里就是这个目录的内容此时可以在里面新建文件、建子目录改动会直接落到磁盘上。如果要在编辑器里建文件资源管理器顶部有新建文件图标输入文件名回车即可。这里有个细节文件名要带扩展名index.html而不是index扩展名决定了语法高亮和后续的格式化、补全行为没扩展名的文件会被当成纯文本。多个不相关的目录想放在一个窗口里管理可以用工作区文件。菜单里选“将文件夹添加到工作区”再另存为.code-workspace文件下次直接打开这个文件就是多根工作区。适合前端和后端分处两个仓库的项目。5. 避坑与排查五条实施中积累的问题记录下面五条都是装完之后才会暴露的问题共同点是安装过程完全正常不报任何错但用起来就是不对。每条按现象、原因、解决三段写。5.1 现象终端里敲 code 提示不是内部或外部命令原因只有两个安装时没勾“添加到 PATH”或者勾了但当前终端读的还是旧环境变量。前者是安装选项问题后者是进程环境问题区分方法很简单新开一个终端窗口再试还不行就是前者。解决分两步。先确认安装目录下的bin子目录里确实有可执行文件有的话说明是 PATH 问题。图形化修复是重跑安装包选择“修改”或“修复”把 PATH 那一项补勾上。手动修复是打开系统环境变量编辑界面在用户变量的 Path 里加一条指向bin目录保存后必须重开终端。macOS 上还有第三种情况用解压方式装的程序在“应用程序”目录里但没建命令行链接。在命令面板里搜“Shell Command”执行“Install code command in PATH”那一项就能补上。这个操作在 Linux 上对应的是手动建软链到/usr/local/bin。5.2 现象中文语言包装了界面还是英文原因通常是三个。一是在扩展市场里装成了别的语言包比如装成了繁体中文包界面会变但只有部分菜单容易被误判成没生效。二是argv.json里的 locale 值和语言包不匹配写成了zh-CN或者别的变体。三是装完只关了窗口没退出进程配置没重新加载。解决办法是先在扩展列表里核对已安装的语言包标识确认是简体中文那个。然后用命令面板打开运行时参数文件检查里面有没有locale: zh-cn这一行值必须是小写的zh-cn没有就手动加上。最后彻底退出编辑器Windows 上看任务管理器确认进程结束macOS 用CmdQ重开生效。5.3 现象打开别人的项目中文注释全是乱码原因是文件编码不一致。Windows 上很多老项目是 GBK 编码编辑器默认按 UTF-8 解析中文就变成方块或者问号。临时解决是点右下角状态栏的编码标识选“通过编码重新打开”在列表里找到 GBK 或者 GB18030 试一下显示正常了就把这个编码记下来。长期解决是在设置里把files.encoding固定成utf8同时把files.autoGuessEncoding打开让编辑器遇到非 UTF-8 文件时自动探测。项目层面则应该统一转成 UTF-8编辑器右下角可以“通过编码保存”选 UTF-8 覆盖原文件转之前记得先提交一次 Git方便出问题回滚。顺带提一句终端乱码这个和文件编码是两码事。Windows 终端默认代码页可能是 936跑一些输出 UTF-8 的脚本会花屏在终端里执行chcp 65001切到 UTF-8 就好想永久生效就写进终端配置。5.4 现象扩展装了但不生效或者提示版本不兼容原因基本是编辑器的版本低于扩展要求的最低版本。扩展详情页有一栏写着所需的编辑器版本装的时候不检查装完才在扩展列表里标红提示。解决要么升级编辑器要么回退扩展版本。升级编辑器最省事帮助菜单里有检查更新或者直接去下载页下新版覆盖安装用户数据会保留。回退扩展需要在扩展详情页的齿轮菜单里选“安装另一个版本”挑一个和当前编辑器版本匹配的装完把自动更新关掉免得第二天又被升回去。我在离线内网环境里经常碰到这种情况编辑器版本被锁定不能升只能一个个把扩展降到兼容版本建议一开始就把扩展清单和版本号记在文档里。5.5 现象重装后提示已存在同版本或者卸载残留导致装不上原因是之前装过系统级版本卸载没清干净注册表里还有记录或者用户级和系统级混装过卸载程序只清除了其中一个。解决顺序是先彻底卸载再清理残留目录。Windows 上的残留主要在用户目录下的应用数据目录和用户目录里的.vscode文件夹前者存配置和缓存后者存扩展和命令行工具。这两个目录删掉等于恢复出厂设置注意先备份settings.json和键盘快捷方式文件。清理完重装选一种安装类型装到底不要再混装。macOS 上残留是用户目录下的.vscode和资源库里的应用支持目录Linux 上是.vscode和.config下的对应目录。注意删.vscode目录会连扩展一起清空。如果只是配置出问题先试着重命名而不是直接删确认能正常启动之后再清。6. 装完怎么验证从空文件夹到一个能打开的页面装完不验证等于没装。我习惯用一条最简路线做验收建一个空文件夹写一个页面用编辑器打开改动后浏览器里能看到变化。整个过程不依赖任何扩展能跑通说明编辑器本体、命令、工作区模型都是好的。先建目录和文件然后以工作区方式打开mkdir verify-demo cd verify-demo code .在编辑器里新建index.html写入下面这几行!DOCTYPE html html langzh-CN head meta charsetUTF-8 / titleverify/title style body { font-family: system-ui, sans-serif; padding: 40px; } h1 { color: #2f6f4e; } /style /head body h1环境验证通过/h1 /body /html保存之后在资源管理器里右键这个文件选择在浏览器中打开或者直接在文件管理器里双击。页面显示标题就说明编辑器写入文件正常。接着回到编辑器改一下标题文字保存浏览器刷新内容跟着变说明文件编码、换行符、保存行为都没问题。再补几项检查按下面的清单逐条过一遍检查项执行方式预期结果版本与架构code --version输出三行架构与机器一致命令可用性任意目录执行code .以该目录为工作区启动界面语言查看菜单与设置项全部为中文扩展生效扩展面板查看已启用列表装的扩展显示为已启用设置加载打开设置 JSON自己改的项都在编码保存含中文的文件状态栏显示 UTF-8最后一项容易被忽略但很关键随便打开一个中文注释较多的旧文件看状态栏编码标识是不是 UTF-8。如果是 GBK 而你没注意到后面写出来的文件在同事机器上就是乱码。这套验收流程走一遍不到五分钟但能提前暴露绝大多数安装期的问题。装完就开写代码、等报错了再回头查环境通常要多花好几倍时间。所以从那以后我每次在新机器上装完编辑器哪怕再赶时间都会强制走一遍这个空文件夹加一个页面的最小验证确认没问题才动手装项目的依赖。希望这套流程帮到你少走几个我当时踩过的坑。本文还有配套的精品资源点击获取