Ctrl+Shift+X（Win/Linux）或Cmd+Shift+X（macOS）是VSCode默认快捷键，用于打开扩展面板；安装VSIX需点击右上角“…”选“Install from VSIX”，且文件必须为未解压的.zip格式，安装后需手动启用或重启生效。
点击扩展面板右上角“…”后选“Install from VSIX”
这是最直观的图形化入口，适用于所有操作系统。打开 VS Code 后按 Ctrl+Shift+X（Windows/Linux）或 Cmd+Shift+X（macOS）唤出扩展面板，确保你看到的是「已安装」「推荐」等标签页所在的主界面——不是设置页、不是终端、也不是资源管理器侧边栏。在面板右上角找到三个点（⋯）按钮，点击后下拉菜单中选择 Install from VSIX。这一步失败常见于误点了扩展面板顶部的搜索框旁的齿轮图标，那个是设置入口，不是安装入口。
.vsix 文件必须保持压缩包状态，不能解压
VS Code 只认 .vsix 后缀的原始 ZIP 包，一旦你双击解压成文件夹，再拖进去或选中就会报错：Unable to install extension: Invalid vsix package。很多用户卡在这一步，以为“解压后复制代码更稳妥”，其实完全相反。验证方法很简单：用 file my-extension.vsix（Linux/macOS）或右键属性看类型（Windows），输出应含 Zip archive data 或 “ZIP 压缩包” 字样。若显示为“文件夹”，说明已被解压，需重新下载或用 zip -r 打包还原。
安装后插件默认禁用，必须手动启用或重启
VS Code 从 1.70 版本起对离线安装的扩展加了安全限制，即使安装成功，也会在扩展列表里显示「已禁用」状态。你得在扩展项右侧点击「启用」按钮，或者直接关闭并重启 VS Code——后者更可靠，尤其当插件有 activationEvents（如 onStartup）时，仅点击启用可能不触发加载。检查是否生效的方法是：打开对应语言文件（如 .py），看有没有语法高亮或智能提示；或运行 code --list-extensions | grep ms-python 确认 ID 已列出且无 [disabled] 标记。
路径含空格或中文时，命令行方式容易失败
如果你改用命令行安装（比如批量部署），code --install-extension /home/user/我的插件/Python-2023.8.0.vsix 这种写法大概率报错，因为 shell 会把空格和中文当作参数分隔符。正确做法是：用单引号包裹路径，或改用绝对路径+英文命名。例如：code --install-extension '/home/user/My Extensions/ms-python.python-2023.8.0.vsix'。另外注意，Windows 上反斜杠 \ 在 PowerShell 中需转义或统一换成正斜杠 /，否则 code --install-extension C:\ext\python.vsix 会被解析成两个参数。
package.json 里的 engines.vscode 版本声明可能被跳过校验，导致功能异常。
