离线安装失败主因是旧版本残留干扰校验与覆盖，导致“安装成功”却无响应、“Extension is corrupt”报错或功能失效；需按顺序清理extensions目录、extensions.json缓存及Windows注册表项，并确保VSCode进程已终止、engines.vscode版本匹配、权限正常。
离线安装失败，八成不是 .vsix 文件本身坏了，而是旧版本残留干扰了校验和覆盖逻辑——VSCode 会检查已安装扩展的元数据、缓存状态、甚至注册表项，任一环节不干净都会导致“安装成功”无响应、“Extension is corrupt”报错，或插件图标亮着但功能全失效。
为什么 code --install-extension 显示成功却没生效
VSCode 的离线安装流程分两步：解压写入 ~/.vscode/extensions/ 目录 + 更新内部 registry 缓存。若旧扩展目录残留（如 esbenp.prettier-vscode-9.10.3），而新 .vsix 解压后生成的是 esbenp.prettier-vscode-9.12.0，两者共存时 VSCode 可能只加载旧版、忽略新版，或因 registry 冲突直接跳过激活。
- 执行命令后没报错 ≠ 插件已启用：用
Developer: Show Running Extensions查看实际加载的版本号 - 状态栏右下角无图标？先确认是否被禁用：
Extensions: Show Enabled Extensions - 插件目录里出现两个同名不同版本的文件夹（如
prettier-vscode-9.10.3和prettier-vscode-9.12.0），说明覆盖失败，必须手动清理旧版
旧版本残留的三个关键位置及清理顺序
别只删 extensions 目录——VSCode 启动时会从多个地方恢复状态。以下三处必须按顺序处理，漏掉任何一项都可能让重装白忙：
-
~/.vscode/extensions/（Linux/macOS）或%USERPROFILE%\.vscode\extensions\（Windows）：重命名该目录为extensions-backup，让 VSCode 启动时重建空白目录 -
~/.vscode/extensions.json（Linux/macOS）或%APPDATA%\Code\User\extensions.json（Windows）：这是扩展启用状态的 registry 缓存，删除它才能清空“已启用”标记 - Windows 注册表项
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Uninstall\{GUID}_is1：若你之前用 User Installer 安装过旧版 VSCode，这个键会让新安装器跳过路径选择并复用旧配置，间接导致扩展加载异常
--force 不起作用时的真实原因
code --install-extension my-ext.vsix --force 本应跳过版本比对和签名校验，但它只在“解压阶段”生效。如果失败发生在后续步骤，--force 就无能为力：
- VSCode 进程仍在后台运行：关掉所有窗口，再打开任务管理器（Windows）或活动监视器（macOS），杀掉所有
Code进程 -
.vsix中extension/package.json的engines.vscode声明高于当前 VSCode 版本：例如值为"^1.85.0"，而你本地是1.84.2，VSCode 会在解压前就拒绝——此时需先修改该字段再打包 - 权限锁定：Linux/macOS 下目标目录被
chown或chmod锁定；Windows 下目录被企业策略设为只读，需以管理员身份运行终端
内网环境验证 .vsix 完整性的最简方法
别依赖文件大小或浏览器下载完成提示——损坏的 .vsix 往往能解压出部分文件，但缺失关键元数据（如 extension.vsixmanifest），导致 VSCode 认为“corrupt”。用系统原生命令快速验证：
- Linux/macOS：
unzip -t my-ext.vsix，输出含OK才算完整 - Windows PowerShell：
Expand-Archive my-ext.vsix -DestinationPath test-unzip -Force，再检查test-unzip/extension/package.json是否可读 - 若报
broken或missing，立刻重下——--force无法修复物理损坏
最容易被忽略的是 Remote-SSH 类插件：它前端部分装在本地，但远端 ~/.vscode-server 目录里的二进制版本必须和本地 VSCode 主版本严格一致。降级 VSCode 后，远端旧 server 不会自动更新，连接会卡在 Starting VS Code Server，必须手动删掉远端该目录再重连。
