真正能用的离线.vsix包必须同时过三关：来源可信（官方Marketplace下载）、版本匹配（engines.vscode与code --version一致）、依赖完整（含native二进制及extensionDependencies）；否则易现签名失效、静默禁用或功能缺失。
离线安装 VSCode 插件失败，八成不是命令写错了，而是你拿到的 .vsix 文件本身就不对——签名失效、版本错位、或压根没带 native 二进制模块。真能用的离线包，必须同时过三关：来源可信、版本匹配、依赖完整。
怎么下载到真正能用的 .vsix 文件
别信第三方打包站，也别从 GitHub Release 页面随手点下载。很多开源插件的 Release 页没同步最新 .vsix，engines.vscode 字段可能还是旧的，装上就静默禁用。
- 最稳方式：打开插件市场页（如
https://marketplace.visualstudio.com/items?itemName=ms-python.python），右侧 Resources 区域点 Download Extension —— 这个按钮生成的是带签名的临时直链，版本和签名都对得上 - 批量/脚本化需求：用
vsixget工具，pipx install vsixget后执行vsixget --latest ms-python.python，它会自动解析页面、选最新兼容版、下载并重命名 - 手动拼 URL（仅限确定版本号时）：
https://marketplace.visualstudio.com/_apis/public/gallery/publishers/{publisher}/vsextensions/{extension_name}/{version}/vspackage，其中publisher和extension_name要从itemName拆（如ms-python.python→ 前半是ms-python，后半是python），version必须去 Version History 页面抄，填错就 404
code --install-extension 报错的三个高频卡点
报错信息往往只有一行，但背后原因很具体。别急着重装，先查这三件事：
-
command not found: code→ 不是 PATH 问题，而是 VSCode 没启用 Shell Command：按Ctrl+Shift+P输入Shell Command: Install 'code' command in PATH回车执行 -
INVALID_SIGNATURE→ 离线环境无法校验证书链，必须加--allow-unverified参数：code --install-extension python.vsix --allow-unverified - 装完不显示、
code --list-extensions也不列出来 → 很可能是 VSCode 正在运行且已加载同名插件，先关掉所有实例（包括托盘进程）再重试
路径、空格、中文这些细节真会报错
VSCode CLI 对路径极其敏感，相对路径、空格、中文都会导致 ENOENT 或截断失败，不是警告，是直接报错。
- Windows PowerShell 下必须加英文双引号：
code --install-extension "C:\my ext\python.vsix" - Linux/macOS 下确保路径是绝对路径：
code --install-extension /home/user/ext/prettier-9.10.3.vsix - 路径含中文？哪怕只是
C:\用户\下载，也必须移到纯英文路径，例如C:\vsix\ - 拖拽安装也一样：VSCode 必须已加载工作区（打开了文件夹或文件），且拖入的是主编辑区，不是侧边栏或设置页
装上了却没功能？大概率是依赖或 native 模块没到位
很多插件（比如 ms-python.python、ms-vscode-remote.remote-ssh）不是“装完即用”，首次启用时才拉取语言服务器或原生二进制模块，离线环境下会卡在“Downloading…”或报 spawn ENOENT。
- 检查
package.json里的extensionDependencies字段：比如装了esbenp.prettier-vscode却没装bradlc.vscode-tailwindcss，格式化 Tailwind 类名就会静默失效 - Remote-SSH 类插件还依赖平台匹配的
vscode-server：ARM Mac 上装 x64 构建的.vsix会报Unsupported platform，得确认包里含darwin-arm64目录 - 校验
.vsix完整性：unzip -t python.vsix（Linux/macOS），报OK才算可读；Windows 推荐用Copy-Item复制生成新文件，别用右键重命名改后缀
真正麻烦的从来不是“怎么装”，而是“怎么确认它真的能跑起来”——版本兼容性要对齐，native 模块要提前部署，依赖链要手动补全。离线环境里，一个没声明的 extensionDependency 就能让整个插件变成摆设。
