VSCode离线安装插件需确保vsix与当前版本（主版本号及架构如x64/arm64）严格兼容，须通过官方市场下载、按依赖顺序安装，并用code --install-extension命令可靠安装；安装后插件须解压至用户extensions目录对应子文件夹，不可直接复制vsix文件。
VSCode离线安装插件时，vsix 文件必须与当前 VSCode 版本兼容
不匹配会导致安装失败并报错 Extension is not compatible with Code。VSCode 的主版本号（如 1.85、1.90）和架构（x64 / arm64 / web）都必须一致。查看当前版本：打开 VSCode → Help → About → 记下 Version 和 Commit 后的括号内容（如 arm64 或 ia32）。
下载插件时务必去官方市场页面（如 https://marketplace.visualstudio.com/items?itemName=ms-python.python），点击右上角 Download Extension，而不是随便找第三方打包的 .vsix。部分插件（如 Pylance）还依赖其他扩展，离线时需一并下载其 .vsix 并按依赖顺序安装。
用命令行安装 .vsix 比图形界面更可靠，尤其在权限受限或路径含空格时
图形界面（Extensions → … → Install from VSIX）在某些企业环境会卡住或静默失败；命令行能直接反馈错误原因。
- Windows：打开终端，运行
code --install-extension "C:path oextension.vsix"（注意路径用双引号包裹） - macOS / Linux：运行
code --install-extension /path/to/extension.vsix - 若提示
command not found: code，说明code命令未加入 PATH —— 在 VSCode 中按Cmd+Shift+P（macOS）或Ctrl+Shift+P（Windows/Linux），输入Shell Command: Install 'code' command in PATH并执行
安装后插件不生效？检查 extensions 目录位置和文件完整性
VSCode 实际把 .vsix 解压到用户数据目录下的 extensions/ 子目录。离线环境常因手动拷贝出错导致结构损坏。
确认路径：
- Windows：
%USERPROFILE%.vscodeextensions - macOS：
$HOME/Library/Application Support/Code/extensions/ - Linux：
$HOME/.vscode/extensions/
每个插件应是一个独立子目录（如 ms-python.python-2024.6.0），内含 package.json 和 node_modules 等。如果只有 .vsix 文件躺在该目录下，说明安装根本没完成 —— 必须通过 code --install-extension 或图形界面触发解压流程，不能直接复制粘贴。
多用户或便携版 VSCode 需单独处理，--extensions-dir 参数可指定自定义路径
企业环境中常见“只读安装目录 + 用户配置分离”场景。此时默认 extensions 目录可能不可写，或需要统一部署到网络共享路径。
启动时指定扩展目录：
code --extensions-dir "\server scode-exts" /path/to/project- 后续所有
--install-extension命令也会写入该目录 - 注意：该参数仅对本次启动生效；如需持久化，可写入快捷方式目标或创建封装脚本
便携版（Portable Mode）会自动使用 data/extensions/ 子目录，无需额外参数 —— 但前提是首次启动时已启用便携模式（存在 data 文件夹且非空）。
插件离线安装真正的难点不在操作步骤，而在于版本链路的闭环验证：从 VSCode 版本 → 插件发布页 → 下载的 .vsix 文件名中的版本号 → 安装后目录名 → package.json 里的 engines.vscode 字段，每一步都得对得上。漏看一个括号里的 arm64，就可能白忙半小时。
