离线安装.vsix插件失败主因是文件损坏、VSCode版本不匹配engines.vscode字段、code命令未加入PATH；需用unzip -t校验完整性、比对版本号、启用Shell Command注册CLI。
离线安装 .vsix 插件总失败？先盯住这三个硬条件
不是操作不对，而是三个基础条件没对齐：.vsix 文件必须完整未解压、VSCode 版本号要匹配 engines.vscode 字段、本地 CLI 必须可用。缺一不可，否则静默跳过或报 “Extension is not a valid VS Code extension”。
- 用
unzip -t your-extension.vsix校验压缩包完整性——报错就重下 - 解压 .vsix，打开
extension/package.json，比对"engines": { "vscode": "^1.85.0" }和你本地code --version输出的第一段（如1.85.2→ 取1.85） - Windows 上双击 .vsix 默认用浏览器打开，无效；必须拖进编辑器主区域，或用 PowerShell 执行
Copy-Item "old.zip" "new.vsix" -Force重命名（别用右键重命名）
命令行安装 vsix 失败报 ENOENT 或 Extension is not compatible？路径和架构才是真因
ENOENT 不是路径写错了，是 code 命令根本没注册到系统 PATH；Extension is not compatible 90% 是架构不匹配或版本越界，不是网络问题。
- 先在 VSCode 里按
Ctrl+Shift+P运行Shell Command: Install 'code' command in PATH，再开新终端 - Linux/macOS 用绝对路径：
code --install-extension /opt/ext/prettier-9.10.3.vsix - Windows 路径含空格必须加引号：
code --install-extension "C:\vscode-ext\ms-python.python-2023.8.0.vsix" - ARM Mac 装 x64 插件（尤其带 native 二进制的，如
pyright）会直接拒载——找带darwin-arm64标识的 .vsix
插件显示“已安装”，但 Python 补全/格式化不工作？离线环境的典型假成功
语言类插件（如 ms-python.python、esbenp.prettier-vscode）首次启用时，会自动下载 LSP server 或 CLI 工具（如 pyright、prettier），这些行为默认走外网。离线环境下，它们卡在状态栏 “Downloading…” 或输出面板报 Failed to fetch，但 UI 仍显示已启用。
- 别重装 .vsix——它只是个壳；必须在有网机器上完整触发一次下载：打开一个
.py文件 → 等状态栏变绿 → 再拷整个扩展目录（如~/.vscode/extensions/ms-python.python-2023.8.0）到内网机对应路径 - 扩展目录名必须完全一致，包括版本号；不能只拷
.vsix，否则node_modules和 native 二进制缺失 - 拷完需彻底退出 VSCode（Windows 查任务管理器杀掉所有
Code.exe进程），再重启
坏味道检测插件离线运行不了？AST 解析器和规则包得一起搬
像基于 vscode.Diagnostic 实现坏味道识别的插件（如检测过长函数、重复代码），离线时不仅依赖插件本身，还依赖其内置的 AST 解析器（如 TypeScript Compiler API 或 Babel）和预置规则数据。部分插件会尝试动态加载规则文件，而这些文件可能被放在远程 CDN 上。
- 检查插件文档是否声明支持离线模式；不声明的，大概率需要手动补全规则资源（常见路径：
extension/rules/或extension/data/） - 若插件使用
fetch加载 JSON 规则，可抓包找出 URL，在有网环境下载后，用插件配置项（如codeSmell.rulesPath）指向本地文件 - 某些插件把规则编译进
dist/的 bundle.js 里，这种最省事；但若看到控制台报Cannot find module './rules/long-function'，说明规则是动态 require 的，必须一并复制
