VSIX文件必须是原始未解压的ZIP压缩包，内部结构完整且顶层目录为extension/；用unzip -l或7-Zip验证，禁用资源管理器双击预览，避免杀毒软件重命名导致静默失败。
vsix 文件必须是原始未解压的压缩包
VSCode 只识别 .vsix 后缀的 ZIP 格式归档，且内部结构必须完整。常见错误是用解压工具点开后又重新打包，或杀毒软件自动重命名（如变成 prettier.vsix.zip），导致拖拽或 code --install-extension 静默失败。
验证方法：unzip -l your-plugin.vsix（Linux/macOS）或用 7-Zip 打开，确认顶层目录为 extension/，不是 package.json 平铺在根下。
Windows 用户注意：资源管理器双击打开 .vsix 会触发自动解压预览，此时再复制该“文件”过去，实际拖的是解压后的临时目录——务必从下载原始位置取未动过的文件。
插件版本与 VSCode 版本必须双向兼容
不光要看插件要求的最低 VSCode 版本（"engines": {"vscode": "^1.85.0"}），还要看你的 VSCode 是否支持该插件的构建目标平台。例如：
- ARM64 Mac（M1/M2/M3）上安装 x64 构建的
.vsix（尤其含 native binary 的，如pyright、esbuild），会加载失败且无提示 - VSCode 1.84 安装标称兼容
^1.80.0的插件，但该插件内部用了 1.85 新增的 API（如workspace.findFiles新参数），仍会功能缺失 - 中文语言包等轻量插件虽跨平台，但部分历史版本（如
code-zh-cn-1.69.x.vsix）在 VSCode 1.90+ 中因 UI 层重构已失效
实操建议：code --version 输出取前两位（如 1.90.2 → 1.90），再对照插件详情页 Requirements 栏或解压后 package.json 的 engines.vscode 字段；对含 native 二进制的插件，优先选带 darwin-arm64、win32-arm64 或 linux-arm64 标识的版本。
依赖插件不会自动安装，必须显式下载
VSCode 离线安装不解析 extensionDependencies 字段，也不会联网拉取依赖。比如装 vue.volar 却没装 @volar/vue-language-service，.vue 文件将无法获得语法高亮和跳转。
正确做法：
- 在联网机器上先完整安装目标插件（含所有依赖），再运行
code --list-extensions --show-versions > extensions.txt - 逐行检查
extensions.txt，对每个 ID 运行vsce download <id>@<version>或手动从 Marketplace 下载对应.vsix - 别信插件页面写的 “Also recommended”，那是推荐算法结果，不是真实依赖树
特别注意：Python 插件（ms-python.python）强依赖 ms-python.pylance 和 ms-python.black-formatter（若启用 Black），漏掉任一，IntelliSense 或格式化即失效。
安装路径和进程状态比命令本身更关键
code --install-extension 失败，90% 不是命令写错，而是环境没到位：
-
code命令不可用？不是 PATH 问题，是没执行Shell Command: Install 'code' command in PATH（Ctrl+Shift+P 输入后回车） - 路径含空格或中文？必须用英文双引号包裹：
code --install-extension "/path/to/my plugin.vsix" - VSCode 正在运行但后台残留？Windows 查任务管理器是否有
Code.exe，macOS/Linux 运行ps aux | grep code，必须彻底退出再安装 - 拖拽安装没反应？确认 VSCode 已加载工作区（不能停留在 Welcome Page）、窗口有焦点、未处于全屏或远程桌面（RDP/TeamViewer）中
最易被忽略的一点：企业环境可能通过组策略禁用扩展安装，右下角状态栏显示 Extensions disabled by policy 时，拖拽和 CLI 全部失效，只能联系管理员或改用手动解压到 Extensions/ 目录（需严格按扩展 ID + 版本命名子目录，并彻底重启）。
