vsix文件必须按目标平台下载，不能“一包多用”；需严格匹配os架构、版本兼容性、依赖插件及签名绕过参数，否则安装后功能静默失效。
vsix 文件必须按目标平台下载，不能“一包多用”
你在 Windows 上下载的 ms-python.python-2026.6.0.vsix，直接扔到 Linux 或 macOS 机器上安装，大概率报 Unsupported platform。VSCode 插件不是纯 JS，很多含原生二进制模块（比如 Python、C++、Remote-SSH 插件），这些模块在 .vsix 包里是按 win32-x64、linux-arm64、darwin-arm64 等平台单独打包的。
实操建议：
- 先确认离线机的平台标识：打开 VSCode → Help → About，看
OS和Architecture字段（如Windows_NT x64或Linux arm64） - 下载时严格匹配：用官方 URL 拼接时，
publisher和extension从插件 ID（如ms-python.python）拆解，version必须抄 Version History 页面 里对应平台的“Latest”版本号，不能填错一位 - 别信 GitHub Release 页：很多插件作者只发源码，不上传
.vsix；即使有，也常缺签名或engines.vscode版本过旧
code --install-extension 命令失败的三个高频原因
code --install-extension 报错信息极简，但实际卡点很具体，常见于离线部署初期：
-
command not found: code→ 不是没装 VSCode，而是没运行 Shell Command: Install 'code' command in PATH（Windows 用 PowerShell，macOS/Linux 用 Terminal 执行一次该命令） -
INVALID_SIGNATURE→ 离线环境无法校验微软证书链，必须加--allow-unverified参数：code --install-extension python.vsix --allow-unverified - 装完
code --list-extensions不显示 → VSCode 正在运行且已加载同名插件，关掉所有 VSCode 实例（包括托盘进程）再重试 - 路径含中文或空格（如
C:\用户\下载\python.vsix）→ 移到纯英文路径，例如C:\vsix\python.vsix，并在命令中加引号：code --install-extension "C:\vsix\python.vsix"
依赖插件必须显式安装，不会自动拉取
VSCode 不会在离线环境下自动解析 package.json 中的 extensionDependencies 并下载依赖项。比如你只装了 esbenp.prettier-vscode，但它依赖 bradlc.vscode-tailwindcss，格式化 Tailwind 类名就会静默失效——界面无报错，功能就是不工作。
查依赖的方法很简单：
- 用
unzip -l python.vsix | grep package.json（Linux/macOS）或 7-Zip 打开.vsix，找到根目录下的package.json - 搜索
"extensionDependencies"字段，里面列的每个 ID 都要单独下载并安装 - 顺序无关紧要，但所有依赖项必须提前准备好，不能边装边找
批量部署前务必验证 VSCode 版本兼容性
插件 package.json 里的 "engines": {"vscode": "^1.85.0"} 是硬约束。如果你的离线机是 VSCode 1.82.2，装 1.85+ 要求的插件，启动时直接静默禁用——扩展列表里显示“已禁用”，但没提示。
操作要点：
- 离线机上执行
code --version，记下完整版本号（如1.82.2） - 在准备机下载插件前，去插件 Version History 页面，筛选出
engines.vscode兼容你版本的最新可用版（例如 1.82.x 分支的最后一个小版本） - 企业级场景建议统一 VSCode 版本：用
code --install-extension配合脚本批量安装时，同步部署对应版本的 VSCode 安装包，避免版本碎片化
最易被忽略的一点：VSCode 自动更新在离线环境中完全不可用，所有插件和编辑器本体的版本锁定都得靠人工核对和归档。一个没签名校验、平台错配、依赖漏装、版本越界的 .vsix，哪怕成功“安装”，也等于没装。
