.vsix文件解压失败主因是压缩包损坏，需用unzip -t校验；重命名改后缀会破坏zip头；拖拽安装需vscode已打开工作区且窗口有焦点；离线安装须严格遵循extensions目录命名规范并彻底重启vscode。
vsix 文件根本没解压成功，是因为压缩包损坏
VSCode 安装 .vsix 时卡在“Installing…”或直接报 Extension is not a valid VS Code extension，90% 不是网络或权限问题，而是文件本身校验失败——它连第一层 ZIP 解压都过不去。
- Windows 下千万别用资源管理器右键“重命名”改后缀（比如把
xxx.zip改成xxx.vsix），这会破坏 ZIP 文件头，VSCode 拒绝加载 - Linux/macOS 运行
unzip -t your-extension.vsix，输出必须是OK；若报错（如bad CRC或invalid compressed data），说明下载不完整或被中间设备篡改 - 用浏览器下载后自动变成
xxx.vsix.zip？别手动删后缀，用 PowerShell 执行：Copy-Item "xxx.vsix.zip" "xxx.vsix" -Force - 用 7-Zip 或 Archive Utility 打开 .vsix，确认顶层目录含
extension/package.json；若看到一堆零散 JS/CSS 文件，说明已被提前解压，不是合法 .vsix
code --install-extension 报 ENOENT 或静默无反应
这不是路径写错了，而是 code 命令根本没注册进系统 PATH，VSCode CLI 工具链没就位。
- 终端运行
which code（macOS/Linux）或where code（Windows），无输出即未注册 - 在 VSCode 中按
Ctrl+Shift+P→ 输入Shell Command: Install 'code' command in PATH→ 回车执行 → 关闭并重启终端 - 临时救急：不用
code命令，改用绝对路径安装
macOS：/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code --install-extension /path/to/xxx.vsix
Linux：/usr/bin/code --install-extension /path/to/xxx.vsix - 别加
sudo：否则插件装到 root 用户目录，普通用户启动 VSCode 后完全看不到
拖拽安装卡住或状态栏无提示
图形界面安装看似简单，但触发条件非常具体，缺一不可。
- VSCode 必须已打开一个工作区（哪怕只是空文件夹），纯欢迎页（Welcome Page）不响应拖拽
- 窗口必须有焦点：任务栏图标高亮、非全屏、未被 RDP/TeamViewer 截断；远程桌面下建议改用命令行
- 拖放目标是编辑器主区域（代码显示区），不是侧边栏、设置页或扩展面板本身
- 右下角状态栏出现
Extensions disabled by policy→ 企业组策略禁用扩展，GUI 和 CLI 都无效，只能手动解压到extensions目录
手动解压后仍不生效，关键在目录名和路径
绕过签名验证直装虽快，但 VSCode 对 extensions 目录结构极其敏感，名字错一位、路径错一层，插件就变“幽灵”。
- 解压命令示例：
unzip xxx.vsix -d /tmp/xxx-unpacked，确保解压后根目录含extension/package.json - 用户 extensions 路径：
Windows：%USERPROFILE%\.vscode\extensions\
macOS：$HOME/.vscode/extensions/
Linux：$HOME/.vscode/extensions/ - 解压后的文件夹必须重命名为
publishername.extensionname-version（如ms-python.python-2024.6.0），不能带空格、中文或特殊字符 - 复制完成后，必须彻底退出 VSCode（包括右下角托盘里的
Code Helper进程），否则缓存不刷新，新插件不会加载
package.json 缺 contributes.localizations 字段（语言包）、或插件要求的 extensionKind（如 workspace）与当前环境冲突。这些都不会报错，只表现为“看不见、点不到、用不了”。
