离线更新VSCode插件需彻底卸载旧版、校验engines.vscode版本兼容性、同步迁移LSP二进制文件；仅覆盖.vsix无效，必须清目录重装并验证状态栏、Output面板及运行扩展三处正常。
离线更新 VSCode 插件不是“换新包重启就行”，核心卡点在三处：旧版残留阻断加载、engines.vscode 版本不匹配、语言服务器（LSP）二进制未就位——任一缺失都会导致插件显示“已启用”但功能完全失效。
为什么直接点“更新”按钮会失败
VSCode 的“检查更新”功能底层依赖 Marketplace API，离线时该请求直接超时或返回 404。更关键的是，旧版本插件的注册表项和缓存文件（如 ~/.vscode/extensions/{id}/package.json 中的 __metadata 字段）会干扰新版加载逻辑，尤其对 CodeGeex、Volar 等含 native 服务的插件，旧进程可能持续占用端口或 socket 文件。
- 必须彻底关闭所有 VSCode 实例（包括系统托盘里隐藏的进程），Windows 可用
taskkill /f /im code.exe，macOS/Linux 执行pkill -f "code --ms-enable-electron-run-as-node" - 不能只覆盖
.vsix文件，必须走完整卸载 → 清目录 → 重装流程 - 部分插件（如
ms-python.python）更新后需手动触发一次 Python 文件打开，才能拉取新版本pyright，离线环境这步必须提前在联网机完成
如何验证新版 .vsix 兼容当前 VSCode
报错 Extension is not compatible with Code 是静默失败最常见原因，VSCode 不提示具体哪一环不兼容，必须人工比对三处：
- 运行
code --version，取输出第一段（如1.90.2→ 主版本为1.90） - 解压
.vsix：用unzip -p your.vsix extension/package.json | grep engines（Linux/macOS）或 7-Zip 打开查看extension/package.json中"engines": {"vscode": "^1.85.0"}字段 - 主版本必须 ≥ 插件声明的最低值；若本地是
1.90.2而插件要求^1.91.0，则不可用 - Help → About 中括号内架构（
x64/arm64）必须与插件构建目标一致；ARM Mac 上安装 x64 版volar-server不报错，但<template>区域零补全
语言服务器（LSP）必须随插件一起迁移
像 volarjs.volar、ms-python.python、esbenp.prettier-vscode 这类插件，.vsix 里只含前端代码，真正的语言分析能力来自子目录下的可执行文件（如 server/volar-server 或 dist/pyright-langserver.js）。离线环境首次启用时无法下载，必须提前打包好完整目录。
- 推荐做法：在同版本联网机器上安装新
.vsix→ 打开一个.vue或.py文件 → 等状态栏显示Volar: Ready或Python: Idle→ 再整份拷贝~/.vscode/extensions/volarjs.volar-1.12.0/到离线机对应路径 - 应急做法：若只有
.vsix，先解压，再从插件 GitHub Release 页面下载对应平台的 LSP 二进制（如volar-server-darwin-arm64），放入server/目录并确保有执行权限（chmod +x） - 验证是否到位：进入离线机的扩展目录，运行
ls -l server/，确认存在带可执行权限的二进制文件，而非空目录或.js源码
CodeGeex 离线更新必须启用 localMode
CodeGeex 插件从 v2.6 起才支持离线 AI 补全，但仅安装新版 .vsix 不够，必须确保配置生效且 UI 响应正常：
- 安装后重启 VSCode，按
Ctrl+Shift+P输入Preferences: Open Settings (JSON)，确认存在"codegeex.localMode": true - 右下角状态栏应出现 CodeGeex 图标（齿轮状），点击后弹出面板显示
Local Mode Enabled；若仍显示Connecting...，说明旧版后台进程未退出干净 - 避免下载发布者为
CodeGeeX Team或名称含Pro的变体包——它们无localMode开关，离线时功能直接降级为纯聊天 - 如遇图标不出现，手动删除
~/.vscode/extensions/aminer.codegeex-*/全目录，再重装，不要保留任何旧文件
真正麻烦的从来不是“怎么装”，而是“怎么确认它真在干活”——打开一个目标文件类型（.py/.vue/.md），盯住状态栏、Output 面板（选对应插件名）、Developer: Show Running Extensions，三处都得看到活跃进程和正常状态，才算落地成功。
