VSCode要求.vsix必须是原始ZIP二进制包，手动解压、重命名、双击打开或压缩软件再保存均会破坏结构，导致“not a valid extension”错误；应使用unzip -t校验完整性，PowerShell用Copy-Item重建文件头，禁用杀软重下，并核对SHA256。
vsix 文件被解压或重命名后无法识别
VSCode 要求 .vsix 必须是原始 ZIP 格式二进制包，任何手动解压、用压缩软件再保存、右键重命名改后缀等操作都会破坏内部结构，导致 Extension is not a valid VS Code extension 错误。
- 用
unzip -t plugin.vsix校验完整性：报错即说明损坏 - 别用 Windows 资源管理器双击打开 .vsix（会自动解压成文件夹），改用命令行
unzip -l plugin.vsix查看顶层是否含extension/package.json - 下载后若发现文件名变成
plugin.vsix.zip或plugin.zip，不是重命名就能解决——要用 PowerShell 执行Copy-Item "old.zip" "new.vsix" -Force重建文件头 - 浏览器或杀毒软件可能静默拦截并重打包，建议关闭实时防护后重新下载，或核对官网页面右下角的 SHA256 值
code --install-extension 报 ENOENT 或 command not found
这不是路径写错了，而是 code 命令根本没注册进当前 shell 环境。VSCode 官方安装包默认不自动配置 PATH，尤其在 SSH、WSL、虚拟机或非交互式终端中极常见。
- 先运行
which code（Linux/macOS）或where code（PowerShell），无输出即未注册 - 临时解决：用绝对路径，如
/usr/bin/code --install-extension /path/to/plugin.vsix（Linux）或/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code --install-extension /path/to/plugin.vsix（macOS） - 永久修复：在 VSCode 中按
Ctrl+Shift+P→ 输入Shell Command: Install 'code' command in PATH→ 回车，再重启终端 - Windows 用户注意：CMD 和 PowerShell 的 PATH 不共享，需分别注册；且不要在命令前加
sudo，否则插件装到 root 目录，普通用户看不到
安装后插件不显示或状态为 “Local” 但不生效
VSCode 静默跳过安装的最常见原因是版本不兼容或依赖缺失——它不会报错，只拒绝加载，插件目录里也不生成对应文件夹。
- 运行
code --version，取前两位（如1.92.2→1.92）；再用unzip -p plugin.vsix extension/package.json | grep engines查"vscode": "^1.93.0"，本地版本必须 ≥ 插件声明的最低版本 - 某些插件（如
ms-python.python）强依赖其他扩展（如ms-toolsai.jupyter），离线时只装主包会失败且无提示，需一并下载dependencies字段列出的所有 ID - ARM 架构设备（M 系列 Mac、树莓派）不能装 x64 版本的 .vsix，去 Marketplace 的
Version History页面手动选darwin-arm64或linux-arm64对应平台版本 - 检查目标目录权限：
~/.vscode/extensions（Linux/macOS）或%USERPROFILE%\.vscode\extensions（Windows）是否可写；企业环境或云桌面常因策略锁死，可用--extensions-dir指向用户主目录下的可写子目录应急
图形界面拖拽或“从 VSIX 安装”无反应
GUI 安装路径依赖后台网络请求做签名验证和调度，断网时它不提示错误，只挂起或丢弃操作——你以为在装，其实什么都没发生。
- 确认 VSCode 窗口有焦点：任务栏图标是否高亮？远程桌面（RDP/TeamViewer）下拖放常被拦截
- 虚拟机共享文件夹（如
/mnt/hgfs）或云桌面映射盘直接拖入大概率失败，务必先复制到本地路径（如~/Downloads/或C:\Users\me\Downloads）再操作 - 路径含中文或空格时，Windows 下必须用英文双引号包裹，且推荐正斜杠：
code --install-extension "C:/vsix/ms-python.python-2024.6.0.vsix" - 如果仍卡在
Installing...，关掉所有 VSCode 进程（包括系统托盘里的Code Helper），再重试；Windows 可用任务管理器结束全部Code.exe
