离线安装VSCode扩展需满足三条件并完成首次激活：①打开文件夹、确保窗口有焦点且未被策略禁用；②校验vsix中engines.vscode版本与本地code --version匹配；③语言类扩展须在有网机完整启用后拷贝整个含language server的扩展目录。
离线安装 VSCode 扩展本身不难，真正卡住人的从来不是“怎么装”，而是装完没反应、补全不生效、状态栏一直卡在 Downloading...——这基本等于白装。根源几乎都在版本校验、依赖未预载、或扩展目录结构错误上。
拖拽 .vsix 到编辑区没反应？先看这三点
这是最常用也最容易失败的操作。VSCode 要求“有焦点 + 有工作区 + 未被策略锁死”三个条件同时满足，缺一不可：
- 必须已打开一个文件夹（哪怕空的），不能停留在启动页或远程连接未就绪状态
- 窗口不能被全屏遮挡，也不能处于远程桌面/虚拟机缩放异常的环境（拖放坐标会偏移）
- 右下角状态栏若显示
Extensions disabled by policy，说明组策略禁用了扩展，GUI 和命令行都会静默失败，此时只能联系管理员
code --install-extension 报 “not compatible” 怎么快速定位
这个报错 95% 是版本不匹配，不是网络问题。VSCode 安装时严格比对 package.json 中的 "engines": {"vscode": "^1.80.0"} 字段和本地版本（code --version 输出如 1.85.2，取前两位 1.85）：
- 用
unzip -p extension.vsix extension/package.json | grep engines（Linux/macOS）或 7-Zip 打开 vsix 查看engines.vscode - Windows 用户可用
tar -xf extension.vsix -C temp解压后手动打开package.json - ARM Mac 装了 x64 构建的插件（尤其含 native 二进制的，如
pyright、esbuild），也会触发同类报错，需找带darwin-arm64标识的版本
Python 补全/格式化不生效？别重装 .vsix，要拷整个扩展目录
语言类插件（如 ms-python.python、esbenp.prettier-vscode）首次启用时，会自动下载 language server 或 CLI 工具（如 pyright、prettier），这些行为默认走外网，离线必然失败：
- 正确做法：在有网机器上完整跑一遍——打开一个
.py文件 → 等状态栏变绿 → 再把整个扩展目录（如~/.vscode/extensions/ms-python.python-2024.6.0/）拷到内网机对应路径 - 只拷
.vsix文件是无效的，native 二进制缺失会导致功能直接降级或崩溃 - 扩展 ID 目录名必须原样保留（含版本号），不能改名或解压后丢掉外层目录，否则 VSCode 启动时识别不到
自动换行设置不生效？优先排查 language-specific 覆盖
按 Alt+Z 能临时开关，但改 settings.json 没反应，大概率是语言专属配置覆盖了全局设置：
- 点击右下角语言标识（如
Python），选Configure 'Python' language settings，检查该语言下editor.wordWrap是否被设为off - 确保配置项拼写准确：
"editor.wordWrap": "on"，不是wordwrap（大小写敏感） - 如果工作区存在
.vscode/settings.json，它会优先于用户设置，需同步修改
离线环境下最易被忽略的点：扩展安装只是第一步，真正让功能跑起来，得提前在有网机器上完成首次激活和依赖拉取——这不是可选动作，是必要前置步骤。
