code --install-extension 是离线安装 vscode 插件的唯一可靠方式，需用绝对路径、匹配主版本、预置 lsp 二进制、绕过策略时手动解压到 extensions 目录并重启。
vscode --install-extension 命令必须用绝对路径
离线更新插件时，code --install-extension 是唯一能触发完整安装流程（解压、校验、注册）的可靠方式。相对图形界面点击“Install from VSIX”，命令行失败会直接报错，便于定位问题。
常见错误现象包括：command not found: code（CLI 未注册）、路径含空格却没加引号、路径是相对路径导致找不到文件。
- Windows 下必须用双引号包裹路径：
code --install-extension "D:\vsix\ms-python.python-2024.12.0.vsix" - Linux/macOS 必须是绝对路径：
code --install-extension /mnt/usb/ext/ms-python.python-2024.12.0.vsix - 若提示
command not found: code，在 VSCode 中按Ctrl+Shift+P输入Shell Command: Install 'code' command in PATH并执行 - 更新已有插件需加
--force参数，否则会跳过：code --install-extension python.vsix --force
插件版本与 VSCode 主版本号必须严格匹配
VSCode 1.92 不兼容为 1.85 编译的插件，哪怕只差一个小版本，也会报错 Extension is not compatible with Code。这不是警告，是硬性拦截。
查看当前 VSCode 版本：Help → About → 记下 Version（如 1.92.2）和括号里的架构（如 x64 或 arm64）。下载插件时，必须确保其 engines.vscode 字段满足该主版本要求。
- 官方市场页面 URL 含插件 ID，例如
https://marketplace.visualstudio.com/items?itemName=ms-python.python，点 “Download Extension” 才保证版本兼容 - 不要从第三方网盘、论坛或非官方 GitHub Release 页面下载 .vsix —— 它们可能被篡改或未签名
- Python 插件 2024.12.0 要求 VSCode ≥1.90；若你用的是 1.89，则必须降级到 Python 插件 2024.8.0
- 更新前先确认目标机器上所有插件的依赖关系，例如 Pylance 依赖 Python 插件，必须先更新 Python，再更新 Pylance
语言插件首次启用会卡在 LSP 下载，离线需预置语言服务器
像 ms-python.python 这类语言插件，安装后默认启用，但第一次激活时会尝试下载 Pyright 或 Pylance 的 LSP 二进制包——这个过程完全离线失败，表现为状态栏一直显示 Downloading...，编辑器无响应。
这不是插件没装好，而是它卡在了离线不可达的子步骤。解决办法不是禁用插件，而是提前把对应版本的语言服务器二进制文件放到位。
- 从插件发布页的 GitHub Releases 找到对应版本的
pyright-*.vsix或pylance-*.vsix，一并下载并安装 - 或手动下载预编译的 LSP 包（如
pyright-1.12.0-darwin-arm64.zip），解压后放入插件目录下的out/node_modules/pyright子路径（路径结构需严格匹配） - 安装完所有相关插件后，务必重启 VSCode —— 仅启用/禁用不触发 LSP 初始化重试
- 验证是否生效：打开一个
.py文件，看右下角是否显示 Python 解释器路径，且无红色下载图标
企业策略禁用扩展时，拖拽安装也失效，只能直投 extensions 目录
当右下角状态栏出现 Extensions disabled by policy，说明组策略（Windows）或管理配置（macOS/Linux）已全局封锁扩展机制。此时 GUI 和 CLI 全部失效，连拖拽 .vsix 到编辑区都不会弹窗。
这是高密环境最常遇到的“静默拦截”。绕过方式是跳过安装流程，直接还原插件解压后的目录结构。
- 用 7-Zip 或
unzip解压.vsix文件，得到一个顶层目录（如ms-python.python-2024.12.0/） - 将整个目录（含
package.json、node_modules、out/）复制到用户 extensions 路径：%USERPROFILE%\.vscode\extensions\（Windows）$HOME/.vscode/extensions/（Linux/macOS） - 必须完全退出 VSCode（任务管理器里杀掉所有
Code.exe或code进程），再重新启动 - 注意：不能只复制
.vsix文件进去，也不能把目录内容平铺进extensions/—— 结构错一位就识别不了
