“导出 VSCode 插件到本地”这个需求，听起来好像就是点几下鼠标的事，但真等你需要的时候，往往都是被逼到墙角了。我第一次遇到这问题，是给公司一台完全隔离内网的开发机配环境：VSCode 装好了，扩展商店却因为网络限制打不开，几个主力插件全都装不上，项目直接卡在编译前。后来我花了一晚上，把常用插件全部导成 vsix 安装包，再拿到那台机器上批量安装，才算彻底解决。今天这篇就把我当时的完整操作过程、脚本写法、踩过的坑都理一遍。不管你是要给离线内网环境准备插件、在团队里统一开发环境，还是单纯想把自己的配置好好备份一份，这篇文章应该都能省下你不少时间。
1. 为什么要把插件导到本地：四个真实场景
1.1 内网开发环境：没有外网时，插件市场就是打不开
很多人一开始不觉得插件导出是刚需，直到站在一台只有内网权限的机器面前才傻眼。军工、金融、政务类项目经常是物理隔离网络，开发机只能访问公司内网资源，VSCode 市场域名完全不通。这时候如果还在纠结“在线安装”，折腾多久都是白费。正确思路只有一个：在能访问外网的机器上，把需要的插件全部导成 vsix 文件，再通过 U 盘或者内网共享目录带进去。
注意： 这之间的关键不是“怎么安装”，而是“怎么把插件完整导出”——包括主插件、依赖插件、对应版本。少了任何一样，装上去也是残缺的。
1.2 团队统一版本：避免“在我电脑上好好的”
团队协作里的一个经典问题：同事 A 的 Python 扩展是 2023.10 版本，同事 B 是 2024.6 版本，结果两边代码提示、Lint 行为都不一样，排查半天发现是插件版本差异。把插件批量导出到本地，放到团队共享库或者 Git 仓库里，大家统一安装同一批 vsix，版本完全锁死，“在我电脑上好好的”这种扯皮会明显减少。
这里我建议的做法是：不只是导出插件，连 settings.json 和 keybindings.json 也一起导出。很多问题表面上是插件版本不一致，深层原因是每个人的配置五花八门。插件版本锁定解决的是“同一套代码能不能跑”，配置同步解决的是“跑起来之后行为一不一致”。
1.3 个人配置备份与迁移：换电脑不再从头折腾
我给自己的一个习惯：每次把常用插件导出一次，打包到一个“开发环境备份”文件夹里。下次换电脑或者重装系统，直接克隆环境，不用再一个个去商店搜索安装。尤其在带新电脑出差、临时借用别人电脑这种场景下，一个 U 盘插进去，几分钟就能把熟悉的开发环境搭好，体验完全不一样。
备份的时候我会把插件和配置放在一起：
- 插件本体：批量导出的 vsix 文件
- 用户配置：
settings.json、keybindings.json、snippets目录 - 插件清单：
code --list-extensions --show-versions的输出
这样的组合可以保证迁移后，不仅插件齐全，你的编辑习惯、快捷键、代码片段偏好也全部保留。
1.4 固定版本防止升级踩雷
扩展商店默认开启自动更新，很多资深用户其实不喜欢这个行为。某个插件新版本引入一个 Bug，或者界面大改影响肌肉记忆，自动更新就给你“惊喜”。虽然有设置项可以关闭自动更新，但手动固定插件版本更稳妥。把当前可用的版本导出成本地 vsix，再配合关闭自动更新，插件就能长期锁定在你验证过的版本上。
具体设置项需要敲extensions.autoUpdate并改为 false，但这个设置默认是所有扩展全局生效。如果只想禁用某个特定插件的更新，需要在设置里配置extensions.autoCheckUpdates以及其他更细粒度的开关。实操中，最保险的组合是“配置关闭自动更新 + 本地 vsix 备份”。
2. 导出前，先搞懂插件在本地到底长什么样
2.1 插件的实际存放目录
VSCode 插件不是藏在什么数据库里的黑盒，它们就是普通文件夹，放在用户目录下的extensions目录中。不同系统路径稍有区别：
| 系统 | 默认插件目录 |
|---|---|
| Windows | %USERPROFILE%\.vscode\extensions |
| Linux | ~/.vscode/extensions |
| macOS | ~/.vscode/extensions |
如果是 VSCode Insiders 版本，目录名会从.vscode变成.vscode-insiders。远程开发模式下插件目录不在本地，这个细节我在第 5 章单独说。
每次安装一个新插件，VSCode 就会在这个目录下解压一个文件夹，文件夹名通常是publisher.extensionName-version，比如ms-python.python-2024.6.0。文件夹里面就是插件的全部代码、资源、清单文件。理解了这一点，你就能明白所谓“导出插件”，本质上就是把在线商店安装好的文件或者原始安装包保存下来。
2.2 插件 ID、VSIX 与市场 URL 的结构
一个插件的唯一标识是“发布者.插件名”，比如ms-python.python，ms-python是发布者，python是插件名。这个 ID 非常重要，后面写脚本下载、拼 URL 都靠它。
VSIX 是 VSCode 插件的标准安装包格式，本质上就是一个改了扩展名的 ZIP 压缩包。里面通常会包含：
extension.vsixmanifest：插件的清单文件，声明 ID、版本、依赖关系extension/：实际的代码和资源目录[Content_Types].xml：打包元数据
你可以用压缩工具直接打开一个 vsix 看看里面长什么样，完全无损。理解了 VSIX 的结构，后面排查“下载文件损坏”“安装报错”之类的问题，思路就清晰很多。
2.3 VSCode 命令行工具的用法
导出插件的核心工具就是code命令。打开终端，输入code --help能看到一堆子命令，跟插件相关的常用有两个：
code --list-extensions：列出已安装插件code --install-extension <名称或路径>：安装插件或本地 vsix
加上--show-versions参数后，code --list-extensions的输出会变成类似：
ms-python.python@2024.6.0 ms-python.debugpy@2024.2.0 eamodio.gitlens@2024.5.2@前面是插件 ID，后面是版本号。这个输出是后面写自动化脚本的“弹药库”。注意，code命令必须在系统 PATH 里才能直接用，如果提示找不到命令，VSCode 里按Ctrl+Shift+P，输入Shell Command: Install 'code' command in PATH执行一遍即可。
2.4 用户级插件与工作区插件要分清
code --list-extensions列出的是用户级插件，也就是全局生效的那些。但 VSCode 还支持工作区级插件，它们存放在项目根目录的.vscode/extensions.json里，一般是团队推荐的插件清单，不一定已经安装到本地。导出时如果只盯着code --list-extensions，会漏掉工作区推荐的插件。
我的处理方式：先检查项目里有没有.vscode/extensions.json，如果有，把里面的recommendations列表也纳入导出范围，逐个对照本地是否已安装。这样导出的插件集才是完整的。
3. 实操：三种导出方式与一个批量脚本
3.1 方式 A：命令行清单 + 市场 URL 批量下载 VSIX
这是我最推荐的一种方式，可控性最强，适合一次导出十几个甚至几十个插件。
第一步，拿到插件清单：
code --list-extensions --show-versions > extensions.txt第二步，分析输出内容。每一行是publisher.extension@version，需要把@前后的信息拆开。
第三步，拼市场下载地址。VSCode 插件市场官方有个公开的下载接口，URL 格式是：
https://marketplace.visualstudio.com/_apis/public/gallery/publishers/{发布者}/vsextensions/{插件名}/{版本号}/vspackage把第一步拿到的内容按规则填进去，就能直接下载对应的 vsix。这里关键一点：URL 里的发布者、插件名、版本号必须和code --list-extensions输出完全一致，大小写都不能错，否则会返回 404。
我写了个 PowerShell 脚本，一次性批量下载全部插件，直接复制就能用：
# export-vscode-extensions.ps1 $extensions = code --list-extensions --show-versions $outputDir = "$PWD\vscode-extensions-backup" New-Item -ItemType Directory -Force -Path $outputDir | Out-Null foreach ($ext in $extensions) { if ($ext -match '^([^.@]+)\.([^@]+)@(.+)$') { $publisher = $Matches[1] $name = $Matches[2] $version = $Matches[3] $file = "$publisher.$name-$version.vsix" $url = "https://marketplace.visualstudio.com/_apis/public/gallery/publishers/$publisher/vsextensions/$name/$version/vspackage" Write-Host "Downloading $file ..." curl.exe -fL -o "$outputDir\$file" $url if ($LASTEXITCODE -eq 0) { Write-Host "OK: $file" } else { Write-Host "FAILED: $file (exit code $LASTEXITCODE)" } } } Write-Host "All done. Files saved in $outputDir"脚本有几个细节值得说明：
- 用
curl.exe而不是 PowerShell 里的Invoke-WebRequest，主要是因为前者对断点续传、重定向、错误码的处理更接近 Linux/macOS 习惯，批量脚本里更好判断成功失败。 -f让 HTTP 404 或 500 时返回非零退出码，避免把错误页面当成插件文件保存下来。- 文件命名用
发布者.插件名-版本.vsix，和本地扩展目录命名风格一致，方便日后人肉识别。
Windows 下如果提示curl.exe不存在（老版本系统），可以用Invoke-WebRequest替换，但判断错误码那里要改成 catch 异常的方式，稍微麻烦一点。建议直接升级到 Win10 1803 以上，自带 curl。
3.2 方式 B：插件商店页面手动下载
如果只需要导出某一个插件，最简单的方法其实在网页端。打开 VSCode 插件市场的网页版（marketplace.visualstudio.com），搜索插件，进入详情页。
在详情页面往往会有一个Version History区块，展开能看到历史版本列表以及每个版本的Download VSIX按钮。点击即可下载对应版本的安装包。这个入口不是所有浏览器布局下都显眼，经常藏在页面下方，需要往下滚动一阵子才能看到。
这个方式适合单个插件、快速救人。缺点是版本号必须自己在页面上确认，没法批量操作。另外，部分插件在商店页面可能没有直接的下载按钮，这时候就要回到方式 A，用命令行清单拼接 URL 来下载。
3.3 方式 C：整目录打包
这是最“暴力”但也最快的方案。不需要下载任何东西，直接把整个扩展目录打成一个压缩包：
tar -czf vscode-extensions-backup.tar.gz -C ~/.vscode extensionsWindows 可以用 PowerShell：
Compress-Archive -Path "$env:USERPROFILE\.vscode\extensions" -DestinationPath "vscode-extensions-backup.zip"整目录打包的优点：快、全，连插件版本目录结构都原样保留。缺点也很明显——平台不通用。如果是在 Windows 上打包的扩展目录，拿到 Linux 上有相当概率因为路径分隔符、依赖的原生模块等问题无法正常运行。所以目录打包适合同平台迁移，不适合跨平台分发。另外，扩展目录里经常混着已经损坏、更新残留的旧版本文件夹，打包前可以先清理一下。
3.4 对比三种方式怎么选
| 方式 | 批量导出 | 固定版本 | 跨平台 | 适合场景 |
|---|---|---|---|---|
| 命令清单 + URL 下载 | 好 | 好 | 好 | 内网分发、团队统一、批量备份 |
| 商店页面手动下载 | 差 | 好 | 好 | 临时救急、单个插件 |
| 整目录打包 | 好 | 差（含残留） | 差 | 同系统快速迁移 |
我的经验是：日常备份优先方式 A，因为产物干净、可控、可复现；临时给同事传一个插件用方式 B；重装系统前赶时间用方式 C 兜底。
4. 拿到 VSIX 之后：离线安装与批量还原
4.1 单机安装一条命令
把 .vsix 文件传到目标机器后，在终端执行：
code --install-extension ./ms-python.python-2024.6.0.vsix没报错的话，状态栏会提示安装完成。也可以加--force强制覆盖同版本。整个过程不需要外网，VSCode 会直接从本地文件解压安装。如果之前安装过同名插件但版本不同，命令会默认拒绝降级，除非加上--force。这个细节很容易让人误以为“离线安装失败”，其实只是版本策略问题。
4.2 批量安装，写个循环脚本
VSIX 文件很多的时候，手动一条条敲命令不现实。把脚本放到 vsix 同级目录下执行即可。
Windows 批处理：
@echo off for %%i in (*.vsix) do ( echo Installing %%i ... code --install-extension "%%i" --force ) echo All extensions installed. pauseBash 版本：
#!/bin/bash for f in *.vsix; do echo "Installing $f ..." code --install-extension "$f" --force done echo "All extensions installed."安装完后用code --list-extensions --show-versions核验一遍，确认数量和版本是否和源机器一致。两边对比时可以重定向到文件然后 diff，省得肉眼一行行看。
4.3 把插件和脚本纳入版本管理
对于团队环境，我建议在 Git 仓库里单独建一个vscode-env/目录，结构如下：
vscode-env/ ├── extensions/ # 所有 vsix 文件 ├── install.sh # 批量安装脚本 ├── settings.json # 统一用户配置 ├── keybindings.json # 统一快捷键 └── README.md # 使用说明这样的好处是：新人入职拉一下仓库，跑一遍install.sh，开发环境就绪。配置修复后提交一次，全团队同步。这本质上就是把“插件依赖”纳入了版本管理，跟前端用 package-lock.json 锁版本是一个思路。我用这套方案之后，团队里“环境问题”相关的求助至少少了一半。
4.4 别忘了配置文件一起迁移
插件装好只是第一步，设置项、快捷键、代码片段不跟着走，还是等于换了个新环境。这几个文件的位置：
| 文件 | 路径 |
|---|---|
| 用户设置 | ~/.config/Code/User/settings.json |
| 快捷键 | ~/.config/Code/User/keybindings.json |
| 代码片段 | ~/.config/Code/User/snippets/ |
Windows 上路径是%APPDATA%\Code\User\。把这些文件一并备份，和插件 VSIX 放在同一个归档目录里，还原时一起复制回对应位置即可。注意 VSCode 远端服务器模式下，配置目录是~/.vscode-server/data/Machine/settings.json，操作远程开发机时不要找错路径。
5. 导出过程中常见的坑与排查心得
5.1 code 命令找不到怎么办
不同系统上code命令的触发方式不完全一样，最常见的报错是 “Command not found”。VSCode 里按Ctrl+Shift+P，输入Shell Command: Install 'code' command in PATH，执行后重启终端即可。macOS 上如果 VSCode 是从非官方渠道安装的，这个入口执行后可能没反应，需要手动检查/usr/local/bin/code软链是否存在。
Windows 上如果终端不认code，直接改用code.cmd也一样能通。批量脚本里为了兼容，可以先判断系统，再决定调code还是code.cmd。
5.2 下载链接 404 或版本号格式不对
最常见的原因是版本号带预发布标识，比如2024.6.0-dev或者1.0.0-insider。这类版本在市场 URL 里有可能是分成多条记录存储，直接拼经典 URL 会 404。解决办法：换用商店页面 Version History 里的稳定版本，或者到插件的 GitHub Releases 里找构建产物。
另一个原因是发布者或插件名的大小写。VSCode 的插件 ID 在内部是大小写不敏感的，但 URL 是大小写敏感的。比如发布者显示为MSPython，URL 里必须原样写MSPython，不能顺手改成小写。
5.3 安装了主插件但功能不生效，多半是漏了依赖
VSCode 有不少插件是“复合体”，装一个会连带要求另一个。典型情况：
ms-python.python依赖ms-python.debugpy、ms-python.vscode-pylancems-toolsai.jupyter依赖ms-python.pythonms-vscode.cmake-tools依赖ms-vscode.cpptools
导出时必须把这些依赖插件也一并导出。怎么判断有没有依赖？看插件详情页的 “Extension Dependencies” 区块，或者在已安装机器上对比code --list-extensions，把多出来的插件一起打包。我在给内网机器准备环境时就是直接把“源机器上所有插件”一股脑导出，完全不挑，省得遗漏。
5.4 远程开发和容器里的插件不在本地
这个坑很隐蔽。如果你平时用 Remote-SSH、Dev Containers 或者 GitHub Codespaces 在远程环境里开发，插件其实安装到了远程端，本地的~/.vscode/extensions目录里可能只有一个远程连接器，根本没有目标插件。此时在本地执行code --list-extensions列出的也不是远程的那套。
解决办法分两种：
- 在远程终端里执行导出命令，生成 VSIX 后再传到需要的地方
- 或者把远程环境作为“源环境”，用第 3 章的方式直接从远程终端批量下载
总之，确认自己“当前在哪里”是排查这个问题的最关键一步。
5.5 安装 vsix 报“损坏”或“无法读取”怎么办
优先用压缩工具直接打开 vsix，看extension.vsixmanifest是否存在。如果打不开，说明文件下载不完整，重新下载。另外，不要手动改 vsix 后缀为 zip 又改回来，部分打包器对文件头有校验，手工改名可能破坏二进制结构。
如果确认文件完整但安装报错，看看是不是目标 VSCode 版本太低，插件清单里声明的engines.vscode版本高于目标版本。这种情况要么升级 VSCode，要么找该插件的更早版本。
5.6 问题速查表
| 问题 | 常见原因 | 处理思路 |
|---|---|---|
code找不到 | PATH 未配置 | VSCode 内执行 Shell Command 安装命令 |
| 下载 404 | 版本号带预发布标识、大小写错误 | 换稳定版本，核对 ID 大小写 |
| 安装后功能缺失 | 依赖插件未安装 | 对照源机器完整导出 |
| 远程环境插件缺失 | 插件不在本地物理机 | 到远程终端执行导出命令 |
| vsix 损坏 | 网络中断下载不完整 | 用压缩工具检查，重新下载 |
| 离线安装降级失败 | 目标版本更高或相同 | 加--force参数覆盖 |
写在最后的一些心得
整套流程跑下来，我最大的体会是：插件导出的核心不是“会一条命令”，而是要先建立“环境即代码”的意识。VSCode 的插件、配置、快捷键，本质上都是开发环境的一部分，它们和仓库里的源码一样值得被版本管理、定期备份。我现在已经养成了习惯，每季度把常用插件重新导出一轮，放到 NAS 上一个固定的备份目录里。真遇到新电脑或者离线环境，直接过去拿就行，不用临时手忙脚乱地找下载入口。
最后再分享一个小技巧：导出 vsix 的时候，顺手把code --list-extensions --show-versions的输出也保存成extensions.txt放在同一目录。这个清单文本文件只有几 KB，却是日后核对版本、恢复环境、排查问题的重要索引。就算 vsix 文件因为年代久远丢了，拿着这份清单也能快速重新从市场拉回来。
