vscode离线插件“装了不工作”主因是依赖未全载、校验失败或后台服务未启动；code --install-extension报“not compatible”需查.vsix内package.json的engines.vscode、os、extensionkind字段是否匹配本地版本与架构，且arm mac不可装x64插件。
局域网离线状态下 VSCode 插件“装了但不工作”，根本不是安装失败，而是依赖没带全、校验被卡住、或后台服务压根没拉起来。
code --install-extension 报 “not compatible with Code” 怎么快速定位
这个错误不是模糊提示，VSCode 在读取 .vsix 内部 package.json 后立刻拒绝，关键就两个字段：
-
"engines": { "vscode": "^1.80.0" }→ 你本地运行code --version，取前两位（如1.85.2→1.85），必须 ≥ 插件声明的最低版本 -
"os": ["win32"]或"extensionKind": ["workspace"]→ ARM Mac 装 x64 插件会静默跳过，无报错；含 native 二进制的插件（如pyright、esbuild）尤其敏感
验证命令（Linux/macOS）：unzip -p your-extension.vsix extension/package.json | grep -E "(engines|os|extensionKind)"；Windows 可用 7-Zip 直接打开查看。
插件已安装但 Python 补全/调试/格式化全失效
离线环境里，ms-python.python 这类插件只是“注册入口”，真正干活的组件（Pylance、debugpy、pyright）默认联网下载。没连过网，它们压根不存在。
- 不能只拷
.vsix文件，得在有网机器上完整触发一次：打开.py文件 → 等 Output 面板显示Pylance启动成功 → 关闭 VSCode - 然后把整个扩展目录（如
~/.vscode/extensions/ms-python.python-2024.6.0/）连同node_modules一起拷到内网机对应路径下 - 确认
settings.json中python.defaultInterpreterPath指向真实 venv 的python可执行文件（Windows 是venv\Scripts\python.exe，macOS/Linux 是venv/bin/python）
启动卡在 “正在检查扩展更新” 转圈
这是内网最典型的假死现象，VSCode 主进程在同步等待 marketplace.visualstudio.com 的 HTTP 请求超时（通常卡 10–30 秒），跟是否启用插件无关，只要插件已安装且 extensions.autoCheckUpdates 为 true（默认值）就会触发。
- 必须同时关闭两项：
"extensions.autoCheckUpdates": false和"extensions.autoUpdate": false - 改完保存后，要完全退出 VSCode（包括托盘进程），再重启，否则不生效
- 如果公司用了组策略（GPO/MDM），还要确认
extensions.gallery.serviceUrl是否被设为空或内网镜像地址；留空比填错强，旧版解析失败反而更卡
拖拽 .vsix 到窗口没反应，但命令行能装
图形界面拖放有严格前置条件，和网络无关，但常被误判为“离线导致”：
- VSCode 必须已加载一个工作区（哪怕空文件夹），纯欢迎页（Welcome Page）不支持拖放
- 窗口必须处于前台且有系统焦点；多显示器缩放偏移、远程 SSH 未就绪、全屏模式下常被拦截
- 右下角状态栏若显示
Extensions disabled by policy，说明企业组策略已锁死——此时code --install-extension也会失败，只能手动解压.vsix到~/.vscode/extensions/并重命名目录为规范格式（如ms-python.python-2024.6.0）
离线部署最易被忽略的点：不是“能不能装”，而是“装完有没有真正跑起来”。很多功能（LSP 启动、CLI 下载、缓存重建）只在首次激活时触发，且不可回退——没联网跑过第一次，后续怎么拷目录都缺关键二进制。
