先确认 cli 是否真正可用：vscode 未启用“shell command”功能会导致 code --install-extension 报 command not found；需在 vscode 中执行 shell command: install 'code' command in path 并重启终端，仅 code --version 成功不代表支持插件安装。
code --install-extension 命令报错或不生效？先确认 CLI 是否真正可用
很多人在内网机器上执行 code --install-extension xxx.vsix 时提示 command not found 或直接无响应，根本原因不是路径写错了，而是 VSCode 没有注册 shell 命令。这不是 PATH 环境变量的问题，而是 VSCode 自身的“Shell Command”功能未启用。
必须手动打开 VSCode → Ctrl+Shift+P → 输入 Shell Command: Install 'code' command in PATH → 回车执行。Windows 下该操作会写入注册表，Linux/macOS 则创建软链接。重启终端后才能识别 code 命令。
常见误判点：
- 看到
code --version能返回版本号，就以为 CLI 可用 —— 实际上这只是 VSCode 自带的简易 launcher，不支持--install-extension - 在 PowerShell 中执行成功，但在 CMD 或 Git Bash 中失败 —— 各 shell 的 PATH 加载逻辑不同，需分别确认
- 执行后提示
Failed to install extension但没报具体错误 —— 很可能是 vsix 文件路径含中文、空格或符号，务必改用绝对路径并避免特殊字符
拖拽安装 vsix 文件为什么有时没反应？关键看窗口状态和文件完整性
把 .vsix 文件直接拖进 VSCode 主编辑区（不是侧边栏、不是设置页）是最稳的离线安装方式，但它对运行时状态极其敏感。
必须同时满足以下条件才有效：
- VSCode 已完全启动，且当前窗口处于焦点（非最小化、非远程桌面后台、非 SSH 远程连接状态）
- 拖入的是原始未解压的
.vsix文件 —— 如果你右键用解压软件打开了它，再拖进去就会失败 - VSCode 未处于全屏模式（某些内网远程桌面会拦截拖放事件）
- 安装完成后插件默认是禁用状态，需手动点击「启用」或重启 VSCode 才能生效
如果拖入后毫无反应，不要反复试，先按 Ctrl+Shift+P 输入 Developer: Toggle Developer Tools，看 Console 是否报 drag and drop is disabled 类错误 —— 那基本就是窗口焦点或远程环境问题。
装完插件却不生效？优先检查 VSCode 版本兼容性和隐式依赖
离线安装最隐蔽的坑不是“没装上”，而是“装上了但不干活”。典型表现是：扩展列表里显示已安装、启用状态为 on、但快捷键无效、命令面板搜不到、右键菜单没新增项。
这时要立刻查两件事：
- 打开
.vsix文件（改后缀为.zip），解压后看根目录下package.json里的"engines": {"vscode": "^1.85.0"}—— 如果你本地 VSCode 是 1.82，它根本不会加载，也不会报错 - 同样在
package.json里找"extensionDependencies"字段，比如ms-python.python依赖ms-python.pylance，漏掉这个，Python 插件的智能提示就全失效 - 别信插件市场页面写的 “Recommended extensions”，那是推荐栏，不是真实依赖树；真实依赖只藏在 vsix 包内部
验证是否加载成功：打开命令面板 → 输入 Developer: Show Running Extensions → 查看目标插件是否出现在列表中，且状态为 Active。
批量部署时怎么避免漏掉依赖？别靠人肉，用 vsce download + package.json 解析
给几十台内网机器统一装插件，靠浏览器一个个下载、记 ID、核对版本，100%漏依赖。正确做法是在一台已配好的联网机器上导出完整依赖链。
分三步走：
- 先用
code --list-extensions > extensions.txt导出所有已启用插件 ID（格式如ms-python.python） - 用
vsce download工具逐个下载对应 vsix：vsce download ms-python.python@2024.6.0—— 注意必须带@version，否则下的是最新版，可能不兼容 - 对每个下载的 vsix，解压后读取
package.json的extensionDependencies，递归补全缺失项，生成最终的 vsix 文件清单
vsce 不是 VSCode 自带命令，需单独安装：npm install -g @vscode/vsce。它比手动拼 Marketplace URL 更可靠，因为会自动处理 publisher 名称、版本重定向和签名校验。
最常被忽略的一点：VSIX 文件本身不包含运行时依赖（比如 Python 插件需要系统已装 Python 解释器），离线部署前必须同步检查插件文档里的“Prerequisites”小节，否则装完也白搭。
