直接拖拽.vsix安装常失败，因VSCode会隐式联网校验签名、publisher ID及依赖；须严格匹配版本、用官方下载包、清空残留目录，并用code --install-extension --force --disable-telemetry --disable-updates命令离线安装。
为什么直接拖拽 .vsix 文件经常失败
VSCode 对插件签名和 Marketplace 元数据有隐式依赖，即使你手动下载了 .vsix，它仍可能在安装时尝试联网校验 publisher ID 或查询依赖插件。常见报错是 Unable to install extension because it is not compatible with the current version of VS Code 或静默失败——表面提示“已安装”，但插件不生效。
实操建议：
- 确认 VSCode 版本与插件要求严格匹配：查看插件页面的
engines.vscode字段（如^1.80.0），用code --version核对本地版本，小版本号差 1 都可能导致拒绝加载 - 不要从第三方镜像或聚合站下载
.vsix；务必通过官方 Marketplace 页面点击 “Download Extension” 按钮获取原始包（URL 含marketplace.visualstudio.com） - 安装前清空
~/.vscode/extensions/（macOS/Linux）或%USERPROFILE%\.vscode\extensions\（Windows）中同名残留目录，避免旧缓存干扰
code --install-extension 命令离线安装的关键细节
命令行方式比 GUI 拖拽更可控，但默认行为仍会触发网络请求（比如检查更新）。必须加参数禁用所有外联行为。
实操建议：
- 使用完整路径调用 VSCode 可执行文件，避免 PATH 中混入旧版：
/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code（macOS）、code（Windows WSL 需用cmd /c code） - 强制关闭自动检查：
code --install-extension /path/to/extension.vsix --force --disable-telemetry --disable-updates - 若插件含本地依赖（如 Python 插件需
pylint），--force不会自动安装依赖项，必须提前手动装好对应 CLI 工具并确保其在$PATH中
多插件批量离线安装时的依赖顺序问题
VSCode 不会自动解析 extensionDependencies 字段并排序安装，直接按文件列表顺序执行 --install-extension 很可能因前置插件未就位而失败（典型如 ms-python.python 依赖 ms-python.pylint，但后者未先装）。
实操建议：
- 用
unzip -p extension.vsix extension/package.json | jq '.extensionDependencies'提取每个插件的依赖声明（需预装jq） - 手动生成拓扑序：把所有插件及其依赖写成 DAG，用
tsort（Linux/macOS）或简易 Python 脚本做拓扑排序 - 最简兜底方案：重复执行安装命令 2–3 轮，每轮跳过已存在插件，靠重试覆盖依赖延迟
离线环境下插件功能受限却无提示的隐蔽情况
很多插件把核心能力（如代码补全、诊断）和在线服务强绑定，例如 tabnine.tabnine-vscode 离线后只剩基础 snippet，github.copilot 完全不可用；这类限制不会在安装阶段报错，而是运行时静默降级。
实操建议：
- 安装前查插件 GitHub 仓库的
README.md或package.json中的activationEvents和contributes字段，确认是否含onLanguage:*以外的激活条件（如onCommand:copilot.*通常意味着需后台服务） - 安装后打开
Developer: Toggle Developer Tools，切换到 Console 标签页，执行插件相关操作，观察是否有Failed to fetch或NetworkError日志 - 对关键插件（如 ESLint、Prettier），务必在离线状态下新建测试文件，手动触发格式化/保存操作，验证实际效果而非仅看状态栏图标
真正卡住离线安装的，往往不是安装动作本身，而是插件运行时对网络的隐式依赖和版本元数据的校验逻辑——这些在安装日志里几乎不体现，得靠主动验证行为来暴露。
