离线安装失败主因是缓存残留或状态不一致导致的“假损坏”——vscode拒绝覆盖旧扩展却不报具体原因，仅卡在installing…或弹出“extension is corrupt”；需先验证vsix完整性、清理残留目录与registry、确保vscode完全退出及权限正常，并用--force强制安装。
离线安装失败，90% 是缓存残留或状态不一致导致的“假损坏”——VSCode 拒绝覆盖旧扩展，但不报具体原因，只卡在 Installing… 或弹 Extension is corrupt。
vsix 安装后提示 “Extension is corrupt” 却能解压成功
这不是文件坏了，是 VSCode 在加载时比对了本地 registry 缓存和磁盘上已存在的同名扩展目录，发现版本、签名或结构不匹配，就直接拒绝激活。常见于手动删过 ~/.vscode/extensions/xxx 但没清 registry，或从非官方渠道下载的 vsix 缺少 extension.vsixmanifest。
- 先确认 vsix 本身完整：
unzip -t my-ext.vsix（Linux/macOS）或Expand-Archive my-ext.vsix -WhatIf（PowerShell），输出OK才可信 - 检查是否真有残留：
ls -la ~/.vscode/extensions/ | grep -i "ext-name"，别只信“没看到文件夹”，有些残留是空目录或隐藏文件 - 不要只卸载插件：右键 → Uninstall 只删 extension 目录，不碰 registry；必须关掉所有 VSCode 进程后再操作
code --install-extension --force 不生效的三个硬性前提
--force 不是万能钥匙，它跳过校验但不绕过运行时约束。以下任一不满足，命令就静默失败：
- VSCode 必须完全退出：包括后台进程（Windows 任务管理器查
Code.exe，macOS/Linux 用ps aux | grep code） - 目标
~/.vscode/extensions/目录需可写：ls -ld ~/.vscode/extensions确认 owner 是当前用户，不是root或被 SIP 锁定（macOS） -
engines.vscode版本必须实际兼容：解压 vsix 后运行unzip -p my-ext.vsix extension/package.json | grep engines，再对比code --version输出的前两位（如1.92.2→1.92）
离线环境如何彻底清理插件状态
缓存不止在 extensions 目录里，registry 和 workspaceState 也会干扰离线安装。最干净的做法是临时重定向用户数据目录，绕过所有旧状态：
- Linux/macOS：启动时加参数
code --user-data-dir=/tmp/vscode-offline --extensions-dir=/tmp/vscode-exts，然后执行code --install-extension /path/to/ext.vsix --force - Windows：用 PowerShell 运行
code --user-data-dir "$env:TEMP\vscode-offline" --extensions-dir "$env:TEMP\vscode-exts" --install-extension "C:\path\to\ext.vsix" --force - 验证是否生效：安装完后打开
Help → About，看右下角显示的 “Extensions path” 是否指向你指定的临时路径
真正麻烦的从来不是 vsix 文件本身，而是 VSCode 把插件状态分散存在至少三处（extensions 目录、registry 缓存、workspaceState），而离线时它不会告诉你哪一处坏了——只能靠重定向或彻底清空来隔离问题。
